How to launch the default app for a URI (XAML)

Artykuł
08/31/2015

Learn how to launch the default app for a Uniform Resource Identifier (URI). URIs allow you to launch another app on the operating system to perform a specific task. For example, if you want to allow the user to send a mail to a contact in your app, you can use the mailto: URI to launch the user’s default e-mail app.

These steps show how to use the Windows.System.Launcher API to launch the default handler for a URI.

Instructions

Step 1: Create the URI

Create a System.Uri (C# or Visual Basic) or Windows.Foundation.Uri (C++) object for the URI to launch. This URI uses the http scheme name.

// The URI to launch
string uriToLaunch = @"https://www.bing.com";
var uri = new Uri(uriToLaunch);

' The URI to launch
Dim uri As New Uri("https://www.bing.com")

// The URI to launch
auto uri = ref new Windows::Foundation::Uri("https://www.bing.com");

Step 2: Launch the URI

The operating system provides several different options for launching the default handler for a URI. These options are described in this chart and in the sections that follow.

Option	Method	Description
Default launch	LaunchUriAsync(Uri)	Launch the specified URI with the default handler.
Launch with a warning dialog	LaunchUriAsync(Uri, LauncherOptions)	The operating system shows a warning dialog before launching the specified URI.
Launch with a recommended app fallback	LaunchUriAsync(Uri, LauncherOptions)	Launch the specified URI 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	LaunchUriAsync(Uri, LauncherOptions) (Windows-only)	Launch the specified URI 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.

These examples use the Windows.System.Launcher.LaunchUriAsync method to launch the URI. This is an overloaded method.

Default launch

Call the Windows.System.Launcher.LaunchUriAsync(Uri) method to launch the URI created in step 1 using the default app for the http URI scheme.

async void DefaultLaunch()
{
   // Launch the URI
   var success = await Windows.System.Launcher.LaunchUriAsync(uri);

   if (success)
   {
      // URI launched
   }
   else
   {
      // URI launch failed
   }
}

async Sub DefaultLaunch()

   ' Launch the URI
   Dim success = await Windows.System.Launcher.LaunchUriAsync(uri)

   If success Then
      ' URI launched
   Else
      ' URI launch failed
   End If

End Sub

void MainPage::DefaultLaunch()
{
   // Launch the URI
   concurrency::task<bool> launchUriOperation(Windows::System::Launcher::LaunchUriAsync(uri));
   launchUriOperation.then([](bool success)
   {
      if (success)
      {
         // URI launched
      }
      else
      {
         // URI launch failed
      }
   });
}

Launch with a warning dialog

Call the Windows.System.Launcher.LaunchUriAsync(Uri, LauncherOptions) method to launch the URI created in step 1 with a warning. Use the Windows.System.LauncherOptions.TreatAsUntrusted property to indicate that the operating system display a warning.

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
   }
}

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

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

Launch with a recommended app fallback

In some cases, the user might not have an app installed to handle the URI 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 URI that you are launching. To do this, call the Windows.System.Launcher.LaunchUriAsync(Uri, 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.

async void DefaultLaunch()
{
   // Set the recommended app
   var options = new Windows.System.LauncherOptions();
   options.PreferredApplicationPackageFamilyName = "Contoso.URIApp_8wknc82po1e";
   options.PreferredApplicationDisplayName = "Contoso URI Ap";

   // Launch the URI and pass in the recommended app 
   // in case the user has no apps installed to handle the URI
   var success = await Windows.System.Launcher.LaunchUriAsync(uri, options);
   if (success)
   {
      // URI launched
   }
   else
   {
      // URI launch failed
   }
}

async Sub DefaultLaunch()

   ' Set the recommended app
   Dim options = Windows.System.LauncherOptions()
   options.PreferredApplicationPackageFamilyName = "Contoso.URIApp_8wknc82po1e";
   options.PreferredApplicationDisplayName = "Contoso URI App";

   ' Launch the URI and pass in the recommended app 
   ' in case the user has no apps installed to handle the URI
   Dim success = await Windows.System.Launcher.LaunchUriAsync(uri, options)

   If success Then
      ' URI launched
   Else
      ' URI launch failed
   End If

End Sub

void MainPage::DefaultLaunch()
{
   // Set the recommended app
   auto launchOptions = ref new Windows::System::LauncherOptions();
   launchOptions-> preferredApplicationPackageFamilyName = "Contoso.URIApp_8wknc82po1e";
   launchOptions-> preferredApplicationDisplayName = "Contoso URI App";

   // Launch the URI and pass in the recommended app 
   // in case the user has no apps installed to handle the URI
   concurrency::task<bool> launchUriOperation(Windows::System::Launcher::LaunchUriAsync(uri, launchOptions));
   launchUriOperation.then([](bool success)
   {
      if (success)
      {
         // URI launched
      }
      else
      {
         // URI launch failed
      }
   });
}

Launch with a Desired Remaining View (Windows-only)

Source apps that call LaunchUriAsync can request that they remain on screen after a URI launch. By default, Windows attempts to share all available space equally between the source app and the target app that handles the URI. 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 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 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.

async void DefaultLaunch()
{
   // Set the desired remaining view.
   var options = new Windows.System.LauncherOptions();
   options.DesiredRemainingView = Windows.UI.ViewManagement.ViewSizePreference.UseLess;

   // Launch the URI 
   var success = await Windows.System.Launcher.LaunchUriAsync(uri, options);

   if (success)
   {
      // URI launched
   }
   else
   {
      // URI launch failed
   }
}

void MainPage::DefaultLaunch()
{
   // Set the desired remaining view.
   auto launchOptions = ref new Windows::System::LauncherOptions();
   launchOptions->DesiredRemainingView = Windows.UI.ViewManagement.ViewSizePreference.UseLess;

   // Launch the URI 
   concurrency::task<bool> launchUriOperation(Windows::System::Launcher::LaunchUriAsync(uri, launchOptions));
   launchUriOperation.then([](bool success)
   {
      if (success)
      {
         // URI launched
      }
      else
      {
         // URI 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 Runtime app or a desktop app.

When launching a URI, 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 URI launches directly to the UI of your app. The user must always take some action to initiate a URI launch. If you attempt to launch a URI and your app isn't in the foreground, the launch will fail and your error callback will be invoked.

You must specify the privateNetworkClientServer capability in order to launch intranet URIs, for example, a file:/// URI that points to a network location.

You can't use this method to launch a URI in the local zone. For example, apps can't use the file:/// URI to access files on the local device. Instead, you must use the Storage APIs to access files. If you attempt to launch an intranet URI without the correct capability or a local zone URI, the launch will fail and your error callback will be invoked.