From 6964675f7eda132fa14ba3aca18e5d8c741123a8 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 14 Apr 2022 10:20:25 -0500 Subject: [PATCH 1/3] Blazor Hybrid link handling behaviors --- aspnetcore/blazor/hybrid/routing.md | 42 ++++++++++++------- aspnetcore/blazor/hybrid/security/index.md | 2 +- aspnetcore/blazor/hybrid/tutorials/maui.md | 2 + .../net-maui-release-candidate-notice.md | 2 +- 4 files changed, 32 insertions(+), 16 deletions(-) diff --git a/aspnetcore/blazor/hybrid/routing.md b/aspnetcore/blazor/hybrid/routing.md index f03f20f1bfac..9755c9845c5f 100644 --- a/aspnetcore/blazor/hybrid/routing.md +++ b/aspnetcore/blazor/hybrid/routing.md @@ -5,7 +5,7 @@ description: Learn how to manage request routing and navigation in Blazor Hybrid monikerRange: '>= aspnetcore-6.0' ms.author: riande ms.custom: "mvc" -ms.date: 02/24/2022 +ms.date: 04/14/2022 no-loc: [".NET MAUI", "Mac Catalyst", "Blazor Hybrid", Home, Privacy, Kestrel, appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] uid: blazor/hybrid/routing --- @@ -15,10 +15,27 @@ This article explains how to manage request routing and navigation in Blazor Hyb [!INCLUDE[](~/blazor/includes/blazor-hybrid-preview-notice.md)] -Register to the `ExternalNavigationStarting` event and set the `ExternalLinkNavigationEventArgs.ExternalLinkNavigationPolicy` property to change link handling behavior. The `ExternalLinkNavigationPolicy` enumeration (`enum`) allows setting link handling behavior to `OpenInExternalBrowser`, `InsecureOpenInWebView`, and `CancelNavigation`. The `ExternalLinkNavigationEventArgs.Uri` property can be used to dynamically set link handling behavior. +[!INCLUDE[](~/blazor/includes/net-maui-release-candidate-notice.md)] + +Default URI request routing behavior: + +* A link is *internal* if the host name of the app's origin URI matches the host name of the request URI. When the host names don't match or if the link sets `target="_blank"`, the link is considered *external*. +* If the link is internal, the link is opened in the `BlazorWebView` by the app. +* If the link is external, the link is opened by an app determined by the device based on the device's registered handler for the link's scheme. +* For links that appear to request a file because the last segment of the URI uses dot notation (for example, `/file.x`, `/Maryia.Melnyk`, `/image.gif`): + * .NET MAUI (WinUI), WPF, and Windows Forms: ? + * .NET MAUI (Android, iOS/Mac Catalyst): ? + +To change the link handling behavior for links that don't set `target="_blank"`, register the `UrlLoading` event and set the `UrlLoadingEventArgs.UrlLoadingStrategy` property. The `UrlLoadingStrategy` enumeration allows setting link handling behavior to any of the following values: + +* `OpenExternally`: Load the URI using an app determined by the device. This is the default strategy for URIs with an external host. +* `OpenInWebView`: Load the URI within the `BlazorWebView`. This is the default strategy for URIs with a host matching the app origin. ***Don't use this strategy for external links unless you can ensure the destination URI is fully trusted.*** +* `CancelNavigation`: Cancels the current URI loading attempt. + +The `UrlLoadingEventArgs.Url` property is used to get or dynamically set the URI. > [!WARNING] -> External links are opened in the device's default browser by default. Opening external links within a `BlazorWebView` can introduce security vulnerabilities and should ***not*** be enabled unless you can ensure that the external links are fully trusted. +> By default, external links are opened in an app determined by the device. Opening external links within a `BlazorWebView` can introduce security vulnerabilities and should ***not*** be enabled unless you can ensure that the external links are fully trusted. ## Namespace @@ -34,10 +51,9 @@ Add the event handler to the constructor of the `Page` where the `BlazorWebView` ```csharp blazorWebView.ExternalNavigationStarting += - (sender, externalLinkNavigationEventArgs) => + (sender, urlLoadingEventArgs) => { - externalLinkNavigationEventArgs.ExternalLinkNavigationPolicy = - ExternalLinkNavigationPolicy.InsecureOpenInWebView; + urlLoadingEventArgs.UrlLoadingStrategy = UrlLoadingStrategy.OpenInWebView; }; ``` @@ -55,23 +71,21 @@ Add the `ExternalNavigationStarting="Handle_ExternalNavigationStarting"` attribu Add the event handler in the `.xaml.cs` file: ```csharp -private void Handle_ExternalNavigationStarting( - object sender, ExternalLinkNavigationEventArgs externalLinkNavigationEventArgs) +private void Handle_ExternalNavigationStarting(object sender, + UrlLoadingEventArgs urlLoadingEventArgs) { - externalLinkNavigationEventArgs.ExternalLinkNavigationPolicy = - ExternalLinkNavigationPolicy.InsecureOpenInWebView; + urlLoadingEventArgs.UrlLoadingStrategy = UrlLoadingStrategy.OpenInWebView; } ``` -## Winforms +## Windows Forms In the constructor of the form containing the `BlazorWebView` control, add the following event registration: ```csharp blazorWebView.ExternalNavigationStarting += - (sender, externalLinkNavigationEventArgs) => + (sender, urlLoadingEventArgs) => { - externalLinkNavigationEventArgs.ExternalLinkNavigationPolicy = - ExternalLinkNavigationPolicy.InsecureOpenInWebView; + urlLoadingEventArgs.UrlLoadingStrategy = UrlLoadingStrategy.OpenInWebView; }; ``` diff --git a/aspnetcore/blazor/hybrid/security/index.md b/aspnetcore/blazor/hybrid/security/index.md index 7997da3b3a66..177d3b12e8a4 100644 --- a/aspnetcore/blazor/hybrid/security/index.md +++ b/aspnetcore/blazor/hybrid/security/index.md @@ -59,7 +59,7 @@ The Android :::no-loc text="Web View"::: is distributed and updated via the [Goo iOS and Mac Catalyst both use [`WKWebView`](https://developer.apple.com/documentation/webkit/wkwebview), a Safari-based control, which is updated by the operating system. Similar to the [Android](#android) case, determine the :::no-loc text="Web View"::: version by reading the :::no-loc text="Web View":::'s [`User-Agent`](https://developer.mozilla.org/docs/Web/HTTP/Headers/User-Agent) string. -### Windows (.NET MAUI, WPF, WinForms) +### Windows (.NET MAUI, WPF, Windows Forms) On Windows, the Chromium-based [Microsoft Edge `WebView2`](/microsoft-edge/webview2/) is required to run Blazor web apps. By default, the newest installed version of `WebView2` (known as the [Evergreen distribution](/microsoft-edge/webview2/concepts/distribution#details-about-the-fixed-version-runtime-distribution-mode)) is used. diff --git a/aspnetcore/blazor/hybrid/tutorials/maui.md b/aspnetcore/blazor/hybrid/tutorials/maui.md index 45389c5516ac..5a7cee18c331 100644 --- a/aspnetcore/blazor/hybrid/tutorials/maui.md +++ b/aspnetcore/blazor/hybrid/tutorials/maui.md @@ -18,6 +18,8 @@ This tutorial shows you how to build and run a .NET MAUI Blazor app. You learn h > * Run the app on Windows > * Run the app in the Android emulator +[!INCLUDE[](~/blazor/includes/blazor-hybrid-preview-notice.md)] + [!INCLUDE[](~/blazor/includes/net-maui-release-candidate-notice.md)] ## Prerequisites diff --git a/aspnetcore/blazor/includes/net-maui-release-candidate-notice.md b/aspnetcore/blazor/includes/net-maui-release-candidate-notice.md index ed1b262fdcb2..79ce4b0d1941 100644 --- a/aspnetcore/blazor/includes/net-maui-release-candidate-notice.md +++ b/aspnetcore/blazor/includes/net-maui-release-candidate-notice.md @@ -2,4 +2,4 @@ no-loc: [".NET MAUI", "Mac Catalyst", "Blazor Hybrid", Home, Privacy, Kestrel, appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] --- > [!IMPORTANT] -> .NET MAUI is a Release Candidate and may be modified before final release. As with other .NET Release Candidates, the 17.2 Preview 3 release is covered by a "go live" support policy, meaning .NET MAUI is supported by Microsoft for production apps. Microsoft makes no warranties, express or implied, with respect to the information provided in Blazor Hybrid articles. +> .NET MAUI is a Release Candidate and may be modified before final release. As with other .NET Release Candidates, the 17.2 Preview 3 release is covered by a "go live" support policy, meaning .NET MAUI is supported by Microsoft for production apps. From 13a83b9df6e8652c17bc290372bad8bbfea2b5dd Mon Sep 17 00:00:00 2001 From: Mackinnon Buck Date: Thu, 14 Apr 2022 11:59:20 -0700 Subject: [PATCH 2/3] Updated routing behavior + small fixes. --- aspnetcore/blazor/hybrid/routing.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/aspnetcore/blazor/hybrid/routing.md b/aspnetcore/blazor/hybrid/routing.md index 9755c9845c5f..9e7411c9ad61 100644 --- a/aspnetcore/blazor/hybrid/routing.md +++ b/aspnetcore/blazor/hybrid/routing.md @@ -19,20 +19,20 @@ This article explains how to manage request routing and navigation in Blazor Hyb Default URI request routing behavior: -* A link is *internal* if the host name of the app's origin URI matches the host name of the request URI. When the host names don't match or if the link sets `target="_blank"`, the link is considered *external*. +* A link is *internal* if the host name and scheme match between the app's origin URI and the request URI. When the host names and schemes don't match or if the link sets `target="_blank"`, the link is considered *external*. * If the link is internal, the link is opened in the `BlazorWebView` by the app. * If the link is external, the link is opened by an app determined by the device based on the device's registered handler for the link's scheme. -* For links that appear to request a file because the last segment of the URI uses dot notation (for example, `/file.x`, `/Maryia.Melnyk`, `/image.gif`): - * .NET MAUI (WinUI), WPF, and Windows Forms: ? - * .NET MAUI (Android, iOS/Mac Catalyst): ? +* For internal links that appear to request a file because the last segment of the URI uses dot notation (for example, `/file.x`, `/Maryia.Melnyk`, `/image.gif`) but don't point to any static content: + * WPF and Windows Forms: The host page content will be returned. + * .NET MAUI: A 404 response will be returned. To change the link handling behavior for links that don't set `target="_blank"`, register the `UrlLoading` event and set the `UrlLoadingEventArgs.UrlLoadingStrategy` property. The `UrlLoadingStrategy` enumeration allows setting link handling behavior to any of the following values: -* `OpenExternally`: Load the URI using an app determined by the device. This is the default strategy for URIs with an external host. -* `OpenInWebView`: Load the URI within the `BlazorWebView`. This is the default strategy for URIs with a host matching the app origin. ***Don't use this strategy for external links unless you can ensure the destination URI is fully trusted.*** -* `CancelNavigation`: Cancels the current URI loading attempt. +* `OpenExternally`: Load the URL using an app determined by the device. This is the default strategy for URIs with an external host. +* `OpenInWebView`: Load the URL within the `BlazorWebView`. This is the default strategy for URLs with a host matching the app origin. ***Don't use this strategy for external links unless you can ensure the destination URI is fully trusted.*** +* `CancelLoad`: Cancels the current URL loading attempt. -The `UrlLoadingEventArgs.Url` property is used to get or dynamically set the URI. +The `UrlLoadingEventArgs.Url` property is used to get or dynamically set the URL. > [!WARNING] > By default, external links are opened in an app determined by the device. Opening external links within a `BlazorWebView` can introduce security vulnerabilities and should ***not*** be enabled unless you can ensure that the external links are fully trusted. @@ -50,7 +50,7 @@ using Microsoft.AspNetCore.Components.WebView; Add the event handler to the constructor of the `Page` where the `BlazorWebView` is constructed: ```csharp -blazorWebView.ExternalNavigationStarting += +blazorWebView.UrlLoading += (sender, urlLoadingEventArgs) => { urlLoadingEventArgs.UrlLoadingStrategy = UrlLoadingStrategy.OpenInWebView; @@ -59,19 +59,19 @@ blazorWebView.ExternalNavigationStarting += ## WPF -Add the `ExternalNavigationStarting="Handle_ExternalNavigationStarting"` attribute to the `BlazorWebView` control in the `.xaml` file: +Add the `UrlLoading="Handle_UrlLoading"` attribute to the `BlazorWebView` control in the `.xaml` file: ```xaml + UrlLoading="Handle_UrlLoading" > ``` Add the event handler in the `.xaml.cs` file: ```csharp -private void Handle_ExternalNavigationStarting(object sender, +private void Handle_UrlLoading(object sender, UrlLoadingEventArgs urlLoadingEventArgs) { urlLoadingEventArgs.UrlLoadingStrategy = UrlLoadingStrategy.OpenInWebView; @@ -83,7 +83,7 @@ private void Handle_ExternalNavigationStarting(object sender, In the constructor of the form containing the `BlazorWebView` control, add the following event registration: ```csharp -blazorWebView.ExternalNavigationStarting += +blazorWebView.UrlLoading += (sender, urlLoadingEventArgs) => { urlLoadingEventArgs.UrlLoadingStrategy = UrlLoadingStrategy.OpenInWebView; From 701b99bcafce93e1259787d4741b1cf5f8f23663 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 14 Apr 2022 15:23:03 -0500 Subject: [PATCH 3/3] Updates --- aspnetcore/blazor/hybrid/routing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/blazor/hybrid/routing.md b/aspnetcore/blazor/hybrid/routing.md index 9e7411c9ad61..554b803d69da 100644 --- a/aspnetcore/blazor/hybrid/routing.md +++ b/aspnetcore/blazor/hybrid/routing.md @@ -23,8 +23,8 @@ Default URI request routing behavior: * If the link is internal, the link is opened in the `BlazorWebView` by the app. * If the link is external, the link is opened by an app determined by the device based on the device's registered handler for the link's scheme. * For internal links that appear to request a file because the last segment of the URI uses dot notation (for example, `/file.x`, `/Maryia.Melnyk`, `/image.gif`) but don't point to any static content: - * WPF and Windows Forms: The host page content will be returned. - * .NET MAUI: A 404 response will be returned. + * WPF and Windows Forms: The host page content is returned. + * .NET MAUI: A 404 response is returned. To change the link handling behavior for links that don't set `target="_blank"`, register the `UrlLoading` event and set the `UrlLoadingEventArgs.UrlLoadingStrategy` property. The `UrlLoadingStrategy` enumeration allows setting link handling behavior to any of the following values: