LaunchUriAsync(Uri, LauncherOptions) | launchUriAsync(Uri, LauncherOptions) method

Launcher.LaunchUriAsync(Uri, LauncherOptions) | launchUriAsync(Uri, LauncherOptions) method

Starts the default app associated with the URI scheme name or the one specified by the ContentType for the specified URI, using the specified options.

Syntax


public:
static IAsyncOperation<bool>^ LaunchUriAsync(
  Uri^ uri, 
  LauncherOptions^ options
)

Parameters

uri

Type: Windows.Foundation.Uri [JavaScript] | System.Uri [.NET] | Windows::Foundation::Uri [C++]

The URI.

options

Type: LauncherOptions

The launch options for the app.

Return value

Type: IAsyncOperation<Boolean>

Returns true if the default app for the URI scheme was launched; falseotherwise.

Remarks

Unless you are calling this API from a Windows desktop application, this API must be called from within an ASTA thread (also known as the UI thread).

This API may also be called from a Windows desktop applications.

This API launches the default app for the scheme whether it be a Universal Windows Platform (UWP) app or Windows desktop application.

The calling app must be visible to the user when this API is invoked.

Unless you are calling this API from a Windows desktop application, this API must be called from within an ASTA thread (also known as a UI thread).

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

You cannot use this method to launch a URI in the local zone. For example, apps cannot use the file:/// protocol to access files on the local computer. Instead, you must use the Storage APIs to access files.

The content type is used to compute a file extension, from the extension the default app is chosen. For example a content type value of ""application/vnd.ms-word.document.12"" is mapped to ".docx" and then the default application for ".docx" is launched. For example:



// this specifies the file type, which is used to bind to Word. 
launcherOptions.ContentType = "application/vnd.ms-word.document.12"; 
// and then this launches the file using the application
Launcher.LaunchUriAsync("http://www.cloud.com/file.docx", options);

When the launch fails for any of the above reasons, the API will succeed and return FALSE from its asynchronous operation.

To enable the user to choose an app instead of launching the default app, set the LauncherOptions.DisplayApplicationPicker | displayApplicationPicker property.

To display a warning that the URI is potentially unsafe, set the LauncherOptions.TreatAsUntrusted | treatAsUntrusted property.

The URI is passed to the associated app. If the associated app is a desktop app, the URI is passed using shell execution mechanisms.

Examples

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

Note  

For Windows apps using JavaScript, call preventDefault in your event handler if the treatAsUntrusted property is set and you are using an a element to launch the URI.

 

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

Requirements (Windows 10 device family)

Device family

Universal, introduced version 10.0.10240.0 [for Xbox, see UWP features that aren't yet supported on Xbox]

API contract

Windows.Foundation.UniversalApiContract, introduced version 1.0

Namespace

Windows.System
Windows::System [C++]

Metadata

Windows.Foundation.UniversalApiContract.winmd

Requirements (Windows 8.x and Windows Phone 8.x)

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]

Namespace

Windows.System
Windows::System [C++]

Metadata

Windows.winmd

See also

Launcher
LaunchUriAsync(Uri)
LaunchUriAsync(Uri, LauncherOptions, ValueSet)
Samples
Association launching sample
Guidelines
Guidelines for file types and URIs
Tasks
How to launch the default app for a URI (JavaScript)
Launch the default app for a URI

 

 

Show:
© 2016 Microsoft