LauncherOptions LauncherOptions LauncherOptions LauncherOptions Class

Specifies the options used to launch the default app for a file or URI.

Syntax

Declaration

public sealed class LauncherOptionspublic sealed class LauncherOptionsPublic NotInheritable Class LauncherOptions

Remarks

Examples

Call the LaunchFileAsync(Windows.Storage.IStorageFile,Windows.System.LauncherOptions) method with DisplayApplicationPicker set to true to launch the app that the user selects for the file from the Open With dialog box.


// 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
        }
      });
  });
async void DefaultLaunch()
{
   // Path to the file in the app package to launch
   string imageFile = @"images\test.png";

   var file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile);

   if (file != null)
   {
      // Set the option to show the picker
      var options = new Windows.System.LauncherOptions();
      options.DisplayApplicationPicker = true;

      // Launch the retrieved file
      bool success = await Windows.System.Launcher.LaunchFileAsync(file, options);
      if (success)
      {
         // File launched
      }
      else
      {
         // File launch failed
      }
   }
   else
   {
      // Could not find file
   }
}
async Sub DefaultLaunch()

   ' Path to the file in the app package to launch
   Dim imageFile = "images\test.png"

   Dim file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile)

   If file IsNot Nothing Then
      ' Set the option to show the picker
      Dim options = Windows.System.LauncherOptions()
      options.DisplayApplicationPicker = True

      ' Launch the retrieved file
      Dim success = await Windows.System.Launcher.LaunchFileAsync(file, options)

      If success Then
         ' File launched
      Else
         ' File launch failed
      End If
   Else
      ' Could not find file
   End If
End Sub
void MainPage::DefaultLaunch()
{
   auto installFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;

   concurrency::task<Windows::Storage::StorageFile^> getFileOperation(installFolder->GetFileAsync("images\\test.png"));
   getFileOperation.then([](Windows::Storage::StorageFile^ file)
   {
      if (file != nullptr)
      {
         // Set the option to show the picker
         auto launchOptions = ref new Windows::System::LauncherOptions();
         launchOptions->DisplayApplicationPicker = true;

         // Launch the retrieved file
         concurrency::task<bool> launchFileOperation(Windows::System::Launcher::LaunchFileAsync(file, launchOptions));
         launchFileOperation.then([](bool success)
         {
            if (success)
            {
               // File launched
            }
            else
            {
               // File launch failed
            }
         });
      }
      else
      {
         // Could not find file
      }
   });
}

Constructors summary

Creates and initializes a new instance of the launcher options object.

Properties summary

Gets or sets the content type that is associated with a URI that represents a file on the network.

Launch a target app and have the currently running source app remain on the screen by sharing the space equally with the target app or by taking up more or less space than the target app.

Gets or sets a value that indicates whether to display the Open With dialog whenever the association launching API is called.

Gets or sets a value that represents a URI that the user should be taken to in the browser if no app exists to handle the file type or URI.

Indicates whether to ignore handlers that can handle http(s) schemes (such as browsers). Instead, launch will fall back to the default browser.

Enables an app to access files that are related to the file used to activate the app.

Gets or sets a value that represents the display name of the app in the store that the user should install if no app exists to handle the file type or URI.

Gets or sets a value that represents the package family name of the app in the Store that the user should install if no app exists to handle the file type or URI.

The package family name of the target package that should be used to launch a file or URI. This property is optional.

Gets or sets a value that indicates whether the system should display a warning that the file or URI is potentially unsafe when starting the app associated with a file or URI.

Gets the user interface (UI) options when starting a default app.

Constructors

  • LauncherOptions()
    LauncherOptions()
    LauncherOptions()
    LauncherOptions()

    Creates and initializes a new instance of the launcher options object.

    public LauncherOptions()public LauncherOptions()Public Function LauncherOptions() As

Properties

  • ContentType
    ContentType
    ContentType
    ContentType

    Gets or sets the content type that is associated with a URI that represents a file on the network.

    public string ContentType { get; set; }public string ContentType { get; set; }Public ReadWrite Property ContentType As string

    Property Value

    • string
      string
      string
      string

      The content type of the URI.

    Remarks

    ContentType may only be specified when launching a URI using LaunchUriAsync(Windows.Foundation.Uri,Windows.System.LauncherOptions).

    The ContentType property allows your app to specify a URI along with a content type. You can use this to associate a URI pointing to a resource on the network with a file type, instead of a URI scheme name. Windows will attempt to use the file type computed from the content type to select the app to launch. The default file handler is then passed the URI instead of a file path. So for example if you have an http:// URI pointing to a .docx file, clicking on it would normally open the browser and begin a file download. By using the ContentType property you can skip the intermediate step and have the default file handler launch immediately. The file handler can then directly access the file on the network using the path embedded in the URI.

    If the handler is unable to work directly on the URI, a copy of the file will be downloaded on their behalf.

    Because ContentType allows you to directly launch a file handler the same security checks that apply to file launching apply to URI launches with this option specified. See Launch the default app for a file and How to launch the default app for a file (JavaScript) for more details on those security checks.

    Note

    This functionality only works if the default file handler supports being passed a URI to a file on the network. The default file handler must also be able to authenticate with the file’s server. Because of these limitations you should only use the ContentType property if you have thoroughly tested the end to end scenario between your app and the app’s that you expect to handle the files being launched

    Important

    This property is only implemented on Desktop devices.

    Examples

    Call the LaunchUriAsync(Windows.Foundation.Uri,Windows.System.LauncherOptions) method with ContentType set to the content type associated with the URI being launched.

    // The URI to launch
    var uriToLaunch = "http://www.contoso.com/SomeFile.docx";
    
    // Create a Uri object from a URI string 
    var uri = new Windows.Foundation.Uri(uriToLaunch);
    
    // Set the URI’s content type
    var options = new Windows.System.LauncherOptions();
    options.contentType = "application/vnd.ms-word.document.12";
    
    Windows.System.Launcher.launchUriAsync(uri, options).then(
       function (success) {
          if (success) {
             // URI launched
          } else {
             // URI launch failed
          }
       });
    
    // The URI to launch
    string uriToLaunch = @"http://www.contoso.com/SomeFile.docx";
    var uri = new Uri(uriToLaunch);
    
    async void DefaultLaunch()
    {
       // Set the URI’s content type
       var options = new Windows.System.LauncherOptions();
       options.ContentType = "application/vnd.ms-word.document.12";
    
       // Launch the URI with the content type
       var success = await Windows.System.Launcher.LaunchUriAsync(uri, options);
    
       if (success)
       {
          // URI launched
       }
       else
       {
          // URI launch failed
       }
    }
    
    // The URI to launch
    auto uri = ref new Windows::Foundation::Uri("http://www.contoso.com/SomeFile.docx");
    
    void MainPage::DefaultLaunch()
    {
       // Set the URI’s content type
       auto launchOptions = ref new Windows::System::LauncherOptions();
       launchOptions->ContentType = "application/vnd.ms-word.document.12";
    
       // Launch the URI with the content type
       concurrency::task<bool> launchUriOperation(Windows::System::Launcher::LaunchUriAsync(uri, launchOptions));
       launchUriOperation.then([](bool success)
       {
          if (success)
          {
             // URI launched
          }
          else
          {
             // URI launch failed
          }
       });
    }
    
    ' The URI to launch
    Dim uri As New Uri("http://www.contoso.com/SomeFile.docx")
    
    async Sub DefaultLaunch()
    
       ' Set the URI’s content type
       Dim options = Windows.System.LauncherOptions()
       options.ContentType = "application/vnd.ms-word.document.12"
    
       ' Launch the URI with the content type
       Dim success = await Windows.System.Launcher.LaunchUriAsync(uri, options)
    
       If success Then
          ' URI launched
       Else
          ' URI launch failed
       End If
    
    End Sub
    
  • DesiredRemainingView
    DesiredRemainingView
    DesiredRemainingView
    DesiredRemainingView

    Launch a target app and have the currently running source app remain on the screen by sharing the space equally with the target app or by taking up more or less space than the target app.

    public ViewSizePreference DesiredRemainingView { get; set; }public ViewSizePreference DesiredRemainingView { get; set; }Public ReadWrite Property DesiredRemainingView As ViewSizePreference

    Property Value

    Remarks

    Source apps that call LaunchUriAsync(Windows.Foundation.Uri) or LaunchFileAsync(Windows.Storage.IStorageFile,Windows.System.LauncherOptions) can request that they remain on screen after a URI or file launch. By default, Windows will attempt to share all available space equally between the source app and the target app that handles the URI or file. Source apps can use the DesiredRemainingView property to indicate to the 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 does not need to remain on screen after the file or URI 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 determining 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.

    Important

    This property is only implemented on Desktop devices.

  • DisplayApplicationPicker
    DisplayApplicationPicker
    DisplayApplicationPicker
    DisplayApplicationPicker

    Gets or sets a value that indicates whether to display the Open With dialog whenever the association launching API is called.

    public bool DisplayApplicationPicker { get; set; }public bool DisplayApplicationPicker { get; set; }Public ReadWrite Property DisplayApplicationPicker As bool

    Property Value

    • bool
      bool
      bool
      bool

      True if the Open With dialog should always be displayed; otherwise false.

    Remarks

    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.

    Important

    This property is only implemented on Desktop devices.

    Examples

    Call the LaunchFileAsync(Windows.Storage.IStorageFile,Windows.System.LauncherOptions) method with DisplayApplicationPicker set to true to launch the app that the user selects for the file from the Open With dialog box.

    
    // 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
            }
          });
      });
    
    async void DefaultLaunch()
    {
       // Path to the file in the app package to launch
       string imageFile = @"images\test.png";
    
       var file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile);
    
       if (file != null)
       {
          // Set the option to show the picker
          var options = new Windows.System.LauncherOptions();
          options.DisplayApplicationPicker = true;
    
          // Launch the retrieved file
          bool success = await Windows.System.Launcher.LaunchFileAsync(file, options);
          if (success)
          {
             // File launched
          }
          else
          {
             // File launch failed
          }
       }
       else
       {
          // Could not find file
       }
    }
    
    async Sub DefaultLaunch()
    
       ' Path to the file in the app package to launch
       Dim imageFile = "images\test.png"
    
       Dim file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile)
    
       If file IsNot Nothing Then
          ' Set the option to show the picker
          Dim options = Windows.System.LauncherOptions()
          options.DisplayApplicationPicker = True
    
          ' Launch the retrieved file
          Dim success = await Windows.System.Launcher.LaunchFileAsync(file, options)
    
          If success Then
             ' File launched
          Else
             ' File launch failed
          End If
       Else
          ' Could not find file
       End If
    End Sub
    
    void MainPage::DefaultLaunch()
    {
       auto installFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;
    
       concurrency::task<Windows::Storage::StorageFile^> getFileOperation(installFolder->GetFileAsync("images\\test.png"));
       getFileOperation.then([](Windows::Storage::StorageFile^ file)
       {
          if (file != nullptr)
          {
             // Set the option to show the picker
             auto launchOptions = ref new Windows::System::LauncherOptions();
             launchOptions->DisplayApplicationPicker = true;
    
             // Launch the retrieved file
             concurrency::task<bool> launchFileOperation(Windows::System::Launcher::LaunchFileAsync(file, launchOptions));
             launchFileOperation.then([](bool success)
             {
                if (success)
                {
                   // File launched
                }
                else
                {
                   // File launch failed
                }
             });
          }
          else
          {
             // Could not find file
          }
       });
    }
    
  • FallbackUri
    FallbackUri
    FallbackUri
    FallbackUri

    Gets or sets a value that represents a URI that the user should be taken to in the browser if no app exists to handle the file type or URI.

    public Uri FallbackUri { get; set; }public Uri FallbackUri { get; set; }Public ReadWrite Property FallbackUri As Uri

    Property Value

    • URI that the user should be taken to in the browser.

    Remarks

    You can only set the fallback URI property with http:// or https:// URI. If this property is set and there is no app installed to handle the file or URI being launched, the user's default browser is launched automatically and navigated to the specified URI. The user will not see an Open With dialog asking to choose an option in this case. You should only use the fallback URI when directing the user to the Windows Store is not appropriate, such as the case when the file or URI is only supported by a desktop app that is not listed on the Store. In all cases where there is an app on the Windows Store that supports the file or URI that you are launching, you should use the PreferredApplicationPackageFamilyName and PreferredApplicationDisplayName to recommend that app to the user.

    You cannot set the preferred application properties and the fallback URI at the same time, since only one fallback may be used. The Launcher API will fail if both fallbacks are set.

    Windows 8.1 In Windows 8.1 only, this property also accepts Windows Store URIs. These URIs can be used as an alternative to the PreferredApplicationPackageFamilyName and PreferredApplicationDisplayName properties to send the user to a specific app in the Store without popping an Open With dialog. This functionality is not supported on Windows Phone 8.1 or converged Windows 10 apps, and its use is not recommended.

    Examples

    Call the LaunchFileAsync(Windows.Storage.IStorageFile,Windows.System.LauncherOptions) method with fallbackUri set to the fallback URI.

    // The URI to launch
    var uriToLaunch = "contoso:somearguments";
    
    // Create a Uri object from a URI string 
    var uri = new Windows.Foundation.Uri(uriToLaunch);
    
    // The fallback URI
    var uriFallback = "http://www.contoso.com/somearguments";
    
    // Create a Uri object from a URI string 
    var fallbackURI = new Windows.Foundation.Uri(uriFallback);
    
    // Set the fallback URI
    var options = new Windows.System.LauncherOptions();
    options.fallbackUri = fallbackURI;
    
    Windows.System.Launcher.launchUriAsync(uri, options).then(
       function (success) {
          if (success) {
             // URI launched
          } else {
             // URI launch failed
          }
       });
    
    // The URI to launch
    string uriToLaunch = @ "contoso:somearguments";
    var uri = new Uri(uriToLaunch);
    
    // The fallback URI
    string uriFallback = @ "http://www.contoso.com/somearguments";
    var fallbackUri = new Uri(fallbackUri);
    
    async void DefaultLaunch()
    {
       // Set the fallback URI
       var options = new Windows.System.LauncherOptions();
       options.ContentType = fallbackUri;
    
       // Launch the URI with the fallback URI
       var success = await Windows.System.Launcher.LaunchUriAsync(uri, options);
    
       if (success)
       {
          // URI launched
       }
       else
       {
          // URI launch failed
       }
    }
    
    
    // The URI to launch
    auto uri = ref new Windows::Foundation::Uri("contoso:somearguments");
    
    // The fallback URI
    auto fallbackUri = ref new Windows::Foundation::Uri("http://www.contoso.com/somearguments");
    
    void MainPage::DefaultLaunch()
    {
       // Set the fallback URI
       auto launchOptions = ref new Windows::System::LauncherOptions();
       launchOptions->ContentType = fallbackUri;
    
       // Launch the URI with the fallback URI
       concurrency::task<bool> launchUriOperation(Windows::System::Launcher::LaunchUriAsync(uri, launchOptions));
       launchUriOperation.then([](bool success)
       {
          if (success)
          {
             // URI launched
          }
          else
          {
             // URI launch failed
          }
       });
    }
    
    ' The URI to launch
    Dim uri As New Uri("contoso:somearguments")
    
    ' The fallback URI
    Dim fallbackUri As New Uri("http://www.contoso.com/somearguments")
    
    async Sub DefaultLaunch()
    
       ' Set the fallback URI
       Dim options = Windows.System.LauncherOptions()
       options.FallbackUri = fallbackUri
    
       ' Launch the URI with the fallback URI
       Dim success = await Windows.System.Launcher.LaunchUriAsync(uri, options)
    
       If success Then
          ' URI launched
       Else
          ' URI launch failed
       End If
    
    End Sub
    
  • IgnoreAppUriHandlers
    IgnoreAppUriHandlers
    IgnoreAppUriHandlers
    IgnoreAppUriHandlers

    Indicates whether to ignore handlers that can handle http(s) schemes (such as browsers). Instead, launch will fall back to the default browser.

    public bool IgnoreAppUriHandlers { get; set; }public bool IgnoreAppUriHandlers { get; set; }Public ReadWrite Property IgnoreAppUriHandlers As bool

    Property Value

    • bool
      bool
      bool
      bool

      True indicates that apps that can handle http(s) schemes will be ignored and instead the URI will be opened in the default browser; false otherwise.

  • NeighboringFilesQuery
    NeighboringFilesQuery
    NeighboringFilesQuery
    NeighboringFilesQuery

    Enables an app to access files that are related to the file used to activate the app.

    public StorageFileQueryResult NeighboringFilesQuery { get; set; }public StorageFileQueryResult NeighboringFilesQuery { get; set; }Public ReadWrite Property NeighboringFilesQuery As StorageFileQueryResult

    Property Value

    Remarks

    Access to files is carefully controlled to protect users from malicious apps. This property gives an application that is activated for a particular file access to other files of the same type. For example, if a photo app is activated for a picture, this property returns the other pictures in the same folder. However, only file types that are declared in the capabilities section of the manifest file will be accessible. For example, only if an app declares the Pictures Library capability in the app manifest will it be possible to access picture files when the app is launched with kind:pictures.

  • PreferredApplicationDisplayName
    PreferredApplicationDisplayName
    PreferredApplicationDisplayName
    PreferredApplicationDisplayName

    Gets or sets a value that represents the display name of the app in the store that the user should install if no app exists to handle the file type or URI.

    public string PreferredApplicationDisplayName { get; set; }public string PreferredApplicationDisplayName { get; set; }Public ReadWrite Property PreferredApplicationDisplayName As string

    Property Value

    • string
      string
      string
      string

      The display name of the app.

    Remarks

    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. Use LauncherOptions.PreferredApplicationDisplayName in conjunction with LauncherOptions.preferredApplicationPackageFamilyName to provide the user with an app in the Windows Store that they can acquire to handle the file. The display name that you use should correspond to the display name of the app in the Windows Store.

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

    Note

    You cannot set the preferred application properties and the fallback URI at the same time, since only one fallback may be used. The Launcher API will fail if both fallbacks are set.

    Important

    This property is only implemented on Desktop devices.

    Examples

    Call the LaunchFileAsync(Windows.Storage.IStorageFile,Windows.System.LauncherOptions) method with preferredApplicationDisplayName set to the display name of an app in the Windows Store and the **preferredApplicationPackageFamilyName ** set to the package family name of an app in the Windows Store.

    // 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 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
            }
          });
      });
    
    async void DefaultLaunch()
    {
       // Path to the file in the app package to launch
       string imageFile = @"images\test.png";
    
       // Get the image file from the package's image directory
       var file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile);
    
       if (file != null)
       {
          // 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
          bool success = await Windows.System.Launcher.LaunchFileAsync(file, options);
          if (success)
          {
             // File launched
          }
          else
          {
             // File launch failed
          }
       }
       else
       {
          // Could not find file
       }
    }
    
    void MainPage::DefaultLaunch()
    {
       auto installFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;
    
       concurrency::task<Windows::Storage::StorageFile^> getFileOperation(installFolder->GetFileAsync("images\\test.png"));
       getFileOperation.then([](Windows::Storage::StorageFile^ file)
       {
          if (file != nullptr)
          {
             // Set the recommended app
             auto launchOptions = ref new Windows::System::LauncherOptions();
             launchOptions-> preferredApplicationPackageFamilyName = “Contoso.FileApp_8wknc82po1e”;
             launchOptions-> 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
             concurrency::task<bool> launchFileOperation(Windows::System::Launcher::LaunchFileAsync(file, launchOptions));
             launchFileOperation.then([](bool success)
             {
                if (success)
                {
                   // File launched
                }
                else
                {
                   // File launch failed
                }
             });
          }
          else
          {
             // Could not find file
          }
       });
    }
    
    async Sub DefaultLaunch()
    
       ' Path to the file in the app package to launch
       Dim imageFile = "images\test.png"
    
       ' Get the image file from the package's image directory
       Dim file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile)
    
       If file IsNot Nothing Then
          ' Set the recommended app
          Dim options = 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
          Dim success = await Windows.System.Launcher.LaunchFileAsync(file)
    
          If success Then
             ' File launched
          Else
             ' File launch failed
          End If
       Else
          ' Could not find file
       End If
    End Sub
    
  • PreferredApplicationPackageFamilyName
    PreferredApplicationPackageFamilyName
    PreferredApplicationPackageFamilyName
    PreferredApplicationPackageFamilyName

    Gets or sets a value that represents the package family name of the app in the Store that the user should install if no app exists to handle the file type or URI.

    public string PreferredApplicationPackageFamilyName { get; set; }public string PreferredApplicationPackageFamilyName { get; set; }Public ReadWrite Property PreferredApplicationPackageFamilyName As string

    Property Value

    • string
      string
      string
      string

      The package family name of the app.

    Remarks

    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. Use LauncherOptions.PreferredApplicationDisplayName in conjunction with LauncherOptions.preferredApplicationPackageFamilyName to provide the user with an app in the Windows Store that they can acquire to handle the file. The display name that you use should correspond to the display name of the app in the Windows Store.

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

    Note

    You cannot set the preferred application properties and the fallback URI at the same time, since only one fallback may be used. The Launcher API will fail if both fallbacks are set.

    Important

    This property is only implemented on Desktop devices.

    Examples

    Call the LaunchFileAsync(Windows.Storage.IStorageFile,Windows.System.LauncherOptions) method with preferredApplicationDisplayName set to the display name of an app in the Windows Store and the **preferredApplicationPackageFamilyName ** set to the package family name of an app in the Windows Store.

    // 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 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
            }
          });
      });
    
    async void DefaultLaunch()
    {
       // Path to the file in the app package to launch
       string imageFile = @"images\test.png";
    
       // Get the image file from the package's image directory
       var file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile);
    
       if (file != null)
       {
          // 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
          bool success = await Windows.System.Launcher.LaunchFileAsync(file, options);
          if (success)
          {
             // File launched
          }
          else
          {
             // File launch failed
          }
       }
       else
       {
          // Could not find file
       }
    }
    
    void MainPage::DefaultLaunch()
    {
       auto installFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;
    
       concurrency::task<Windows::Storage::StorageFile^> getFileOperation(installFolder->GetFileAsync("images\\test.png"));
       getFileOperation.then([](Windows::Storage::StorageFile^ file)
       {
          if (file != nullptr)
          {
             // Set the recommended app
             auto launchOptions = ref new Windows::System::LauncherOptions();
             launchOptions-> preferredApplicationPackageFamilyName = “Contoso.FileApp_8wknc82po1e”;
             launchOptions-> 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
             concurrency::task<bool> launchFileOperation(Windows::System::Launcher::LaunchFileAsync(file, launchOptions));
             launchFileOperation.then([](bool success)
             {
                if (success)
                {
                   // File launched
                }
                else
                {
                   // File launch failed
                }
             });
          }
          else
          {
             // Could not find file
          }
       });
    }
    
    async Sub DefaultLaunch()
    
       ' Path to the file in the app package to launch
       Dim imageFile = "images\test.png"
    
       ' Get the image file from the package's image directory
       Dim file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile)
    
       If file IsNot Nothing Then
          ' Set the recommended app
          Dim options = 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
          Dim success = await Windows.System.Launcher.LaunchFileAsync(file)
    
          If success Then
             ' File launched
          Else
             ' File launch failed
          End If
       Else
          ' Could not find file
       End If
    End Sub
    
  • TargetApplicationPackageFamilyName
    TargetApplicationPackageFamilyName
    TargetApplicationPackageFamilyName
    TargetApplicationPackageFamilyName

    The package family name of the target package that should be used to launch a file or URI. This property is optional.

    public string TargetApplicationPackageFamilyName { get; set; }public string TargetApplicationPackageFamilyName { get; set; }Public ReadWrite Property TargetApplicationPackageFamilyName As string

    Property Value

    • string
      string
      string
      string

      The package family name of the target package that should be used to launch a file or URI. This property is optional.

  • TreatAsUntrusted
    TreatAsUntrusted
    TreatAsUntrusted
    TreatAsUntrusted

    Gets or sets a value that indicates whether the system should display a warning that the file or URI is potentially unsafe when starting the app associated with a file or URI.

    public bool TreatAsUntrusted { get; set; }public bool TreatAsUntrusted { get; set; }Public ReadWrite Property TreatAsUntrusted As bool

    Property Value

    • bool
      bool
      bool
      bool

      True if the warning should be displayed; otherwise false.

    Remarks

    Important

    This property is only implemented on Desktop devices.

    Examples

    This sample uses LaunchUriAsync(Windows.Foundation.Uri,Windows.System.LauncherOptions) to launch a URI with a warning. The TreatAsUntrusted property indicates that the system should display a warning.

    
    // The URI to launch
    var uriToLaunch = "http://www.bing.com";
    
    // Create a Uri object from a URI string 
    var uri = new Windows.Foundation.Uri(uriToLaunch);
    
    // Launch the URI with a warning prompt
    var options = new Windows.System.LauncherOptions();
    options.treatAsUntrusted = true;
    
    Windows.System.Launcher.launchUriAsync(uri, options).then(
       function (success) {
          if (success) {
             // URI launched
          } else {
             // URI launch failed
          }
       });
    
    // The URI to launch
    string uriToLaunch = @"http://www.bing.com";
    var uri = new Uri(uriToLaunch);
    
    async void DefaultLaunch()
    {
       // Set the option to show a warning
       var options = new Windows.System.LauncherOptions();
       options.TreatAsUntrusted = true;
    
       // Launch the URI with a warning prompt
       var success = await Windows.System.Launcher.LaunchUriAsync(uri, options);
    
       if (success)
       {
          // URI launched
       }
       else
       {
          // URI launch failed
       }
    }
    
    ' The URI to launch
    Dim uri As New Uri("http://www.bing.com")
    
    async Sub DefaultLaunch()
    
       ' Set the option to show a warning
       Dim options = Windows.System.LauncherOptions()
       options.TreatAsUntrusted = True
    
       ' Launch the URI with a warning prompt
       Dim success = await Windows.System.Launcher.LaunchUriAsync(uri, options)
    
       If success Then
          ' URI launched
       Else
          ' URI launch failed
       End If
    
    End Sub
    
    // The URI to launch
    auto uri = ref new Windows::Foundation::Uri("http://www.bing.com");
    
    void MainPage::DefaultLaunch()
    {
       // Set the option to show a warning
       auto launchOptions = ref new Windows::System::LauncherOptions();
       launchOptions->TreatAsUntrusted = true;
    
       // Launch the URI with a warning prompt
       concurrency::task<bool> launchUriOperation(Windows::System::Launcher::LaunchUriAsync(uri, launchOptions));
       launchUriOperation.then([](bool success)
       {
          if (success)
          {
             // URI launched
          }
          else
          {
             // URI launch failed
          }
       });
    }
    
  • UI
    UI
    UI
    UI

    Gets the user interface (UI) options when starting a default app.

    public LauncherUIOptions UI { get; }public LauncherUIOptions UI { get; }Public ReadOnly Property UI As LauncherUIOptions

    Property Value

    Remarks

    Important

    This property is only implemented on Desktop devices.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.System.dll