diff --git a/aspnetcore/blazor/hybrid/routing.md b/aspnetcore/blazor/hybrid/routing.md index f03f20f1bfac..554b803d69da 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 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 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 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: + +* `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 URL. > [!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 @@ -33,45 +50,42 @@ using Microsoft.AspNetCore.Components.WebView; Add the event handler to the constructor of the `Page` where the `BlazorWebView` is constructed: ```csharp -blazorWebView.ExternalNavigationStarting += - (sender, externalLinkNavigationEventArgs) => +blazorWebView.UrlLoading += + (sender, urlLoadingEventArgs) => { - externalLinkNavigationEventArgs.ExternalLinkNavigationPolicy = - ExternalLinkNavigationPolicy.InsecureOpenInWebView; + urlLoadingEventArgs.UrlLoadingStrategy = UrlLoadingStrategy.OpenInWebView; }; ``` ## 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, ExternalLinkNavigationEventArgs externalLinkNavigationEventArgs) +private void Handle_UrlLoading(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) => +blazorWebView.UrlLoading += + (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.