CoreWebView2.LaunchingExternalUriScheme Event
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
LaunchingExternalUriScheme is raised when a navigation request is made to a URI scheme that is registered with the OS.
public event EventHandler<Microsoft.Web.WebView2.Core.CoreWebView2LaunchingExternalUriSchemeEventArgs> LaunchingExternalUriScheme;member this.LaunchingExternalUriScheme : EventHandler<Microsoft.Web.WebView2.Core.CoreWebView2LaunchingExternalUriSchemeEventArgs> Public Custom Event LaunchingExternalUriScheme As EventHandler(Of CoreWebView2LaunchingExternalUriSchemeEventArgs) Event Type
Examples
void WebView_LaunchingExternalUriScheme(object target, CoreWebView2LaunchingExternalUriSchemeEventArgs args)
{
// A deferral may be taken for the event so that the CoreWebView2
// doesn't examine the properties we set on the event args until
// after we call the Complete method asynchronously later.
// This will give the user more time to decide whether to launch
// the external URI scheme or not.
// A deferral doesn't need to be taken in this case, so taking
// a deferral is commented out here.
// CoreWebView2Deferral deferral = args.GetDeferral();
// System.Threading.SynchronizationContext.Current.Post((_) =>
// {
// using (deferral)
// {
if (String.Equals(args.Uri, "calculator:///", StringComparison.OrdinalIgnoreCase))
{
// Set the event args to cancel the event and launch the
// calculator app. This will always allow the external URI scheme launch.
args.Cancel = true;
ProcessStartInfo info = new ProcessStartInfo
{
FileName = args.Uri,
UseShellExecute = true
};
Process.Start(info);
}
else if (String.Equals(args.Uri, "malicious:///", StringComparison.OrdinalIgnoreCase))
{
// Always block the request in this case by cancelling the event.
args.Cancel = true;
}
else if (String.Equals(args.Uri, "contoso:///", StringComparison.OrdinalIgnoreCase))
{
// To display a custom dialog we cancel the launch, display
// a custom dialog, and then manually launch the external URI scheme
// depending on the user's selection.
args.Cancel = true;
string text = "Launching External URI Scheme";
if (args.InitiatingOrigin != "")
{
text += "from ";
text += args.InitiatingOrigin;
}
text += " to ";
text += args.Uri;
text += "\n";
text += "Do you want to grant permission?";
string caption = "Launching External URI Scheme request";
MessageBoxButton btnMessageBox = MessageBoxButton.YesNo;
MessageBoxImage icnMessageBox = MessageBoxImage.None;
MessageBoxResult resultbox = MessageBox.Show(text, caption, btnMessageBox, icnMessageBox);
switch (resultbox)
{
case MessageBoxResult.Yes:
ProcessStartInfo info = new ProcessStartInfo
{
FileName = args.Uri,
UseShellExecute = true
};
Process.Start(info);
break;
case MessageBoxResult.No:
break;
}
}
else
{
// Do not cancel the event, allowing the request to use the default dialog.
}
// }
// }, null);
}
Remarks
The LaunchingExternalUriScheme event handler may suppress the default dialog or replace the default dialog with a custom dialog. If a CoreWebView2Deferral is not taken on the event args, the external URI scheme launch is blocked until the event handler returns. If a deferral is taken, the external URI scheme launch is blocked until the CoreWebView2Deferral is completed. The host also has the option to cancel the URI scheme launch.
The NavigationStarting and NavigationCompleted events will be raised, regardless of whether the Cancel property is set to true or false. The NavigationCompleted event will be raised with the @CoreWebView2NavigationCompletedEventArgs.IsSuccess property set to `false` and the @CoreWebView2NavigationCompletedEventArgs.WebErrorStatus property set to @CoreWebView2WebErrorStatus$.ConnectionAborted regardless of whether the host sets the @CoreWebView2LaunchingExternalUriSchemeEventArgs.Cancel property. The SourceChanged, ContentLoading and HistoryChanged events will not be raised for this navigation to the external URI scheme regardless of the Cancel property. The LaunchingExternalUriScheme event will be raised after the NavigationStarting event and before the NavigationCompleted event.
The default CoreWebView2Settings will also be updated upon navigation to an external URI scheme. If a setting on the CoreWebView2Settings interface has been changed, navigating to an external URI scheme will trigger the CoreWebView2Settings to update.
The WebView2 may not display the default dialog based on user settings, browser settings, and whether the origin is determined as a trustworthy origin; however, the event will still be raised.
If the request is initiated by a cross-origin frame without a user gesture, the request will be blocked and the LaunchingExternalUriScheme event will not be raised. A URI scheme may be blocked for safety reasons. In this case the LaunchingExternalUriScheme event will not be raised. The default dialog may show an "always allow" checkbox which allows the user to opt-in to relaxed security (i.e. skipping future default dialogs) for the combination of the URI scheme and the origin of the page initiating this external URI scheme launch. The checkbox is offered so long as the group policy to show the checkbox is not explicitly disabled and there is a trustworthy initiating origin. If the user has checked this box, future attempts to launch this URI scheme will still raise the event.