diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index 9f4f52a9e8..5809b2a0ea 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -1283,8 +1283,12 @@ items: - name: Win32 items: -# - name: WebView2 in Win32 apps -# href: ./webview2/platforms/win32.md + - name: WebView2 in Win32 apps + href: ./webview2/platforms/win32.md + + - name: Get started with WebView2 in Win32 apps + href: ./webview2/get-started/win32.md + displayName: Win32_GettingStarted # repo dir name - name: Win32 sample app href: ./webview2/samples/webview2apissample.md @@ -1298,40 +1302,40 @@ href: ./webview2/samples/webview2browser.md displayName: WebView2Browser # repo dir name - - name: Get started with WebView2 in Win32 apps - href: ./webview2/get-started/win32.md - displayName: Win32_GettingStarted # repo dir name - - name: WinUI 2 (UWP) items: -# - name: WebView2 in WinUI 2 (UWP) apps -# href: ./webview2/platforms/winui2-uwp.md - - - name: WinUI 2 (UWP) sample app - href: ./webview2/samples/webview2_sample_uwp.md - displayName: webview2_sample_uwp # repo dir name + - name: WebView2 in WinUI 2 (UWP) apps + href: ./webview2/platforms/winui2-uwp.md - name: Get started with WebView2 in WinUI 2 (UWP) apps href: ./webview2/get-started/winui2.md displayName: WinUI2_GettingStarted # repo dir name + - name: WinUI 2 (UWP) sample app + href: ./webview2/samples/webview2_sample_uwp.md + displayName: webview2_sample_uwp # repo dir name + - name: WinUI 3 (Windows App SDK) items: -# - name: WebView2 in WinUI 3 (Windows App SDK) apps -# href: ./webview2/platforms/winui3-windows-app-sdk.md - - - name: WinUI 3 (Windows App SDK) sample app - href: ./webview2/samples/webview2-winui3-sample.md - displayName: WebView2_WinUI3_Sample # repo dir name + - name: WebView2 in WinUI 3 (Windows App SDK) apps + href: ./webview2/platforms/winui3-windows-app-sdk.md - name: Get started with WebView2 in WinUI 3 (Windows App SDK) apps href: ./webview2/get-started/winui.md displayName: WinUI3_GettingStarted # repo dir name - - name: WebView2 in WPF apps + - name: WinUI 3 (Windows App SDK) sample app + href: ./webview2/samples/webview2-winui3-sample.md + displayName: WebView2_WinUI3_Sample # repo dir name + + - name: WPF items: -# - name: WebView2 apps on Win32 -# href: ./webview2/platforms/wpf.md + - name: WebView2 in WPF apps + href: ./webview2/platforms/wpf.md + + - name: Get started with WebView2 in WPF apps + href: ./webview2/get-started/wpf.md + displayName: WPF_GettingStarted # repo dir name - name: WPF sample app href: ./webview2/samples/webview2wpfbrowser.md @@ -1341,39 +1345,35 @@ href: ./webview2/samples/wv2cdpextensionwpfsample.md displayName: WV2CDPExtensionWPFSample # repo dir name - - name: Get started with WebView2 in WPF apps - href: ./webview2/get-started/wpf.md - displayName: WPF_GettingStarted # repo dir name - - name: WinForms items: -# - name: WebView2 in WinForms apps -# href: ./webview2/platforms/winforms.md - - - name: WinForms sample app - href: ./webview2/samples/webview2windowsformsbrowser.md - displayName: WebView2WindowsFormsBrowser # repo dir name + - name: WebView2 in WinForms apps + href: ./webview2/platforms/winforms.md - name: Get started with WebView2 in WinForms apps href: ./webview2/get-started/winforms.md displayName: WinForms_GettingStarted # repo dir name + - name: WinForms sample app + href: ./webview2/samples/webview2windowsformsbrowser.md + displayName: WebView2WindowsFormsBrowser # repo dir name + - name: HoloLens 2 Unity items: -# - name: WebView2 in HoloLens 2 Unity apps -# href: ./webview2/platforms/hololens-2-unity.md + - name: WebView2 in HoloLens 2 Unity apps + href: ./webview2/platforms/hololens-2-unity.md - name: Get started with WebView2 in HoloLens 2 Unity apps (Preview) href: ./webview2/get-started/hololens2.md displayName: HoloLens2_GettingStarted # repo dir name - - name: WebView2 sample apps - href: ./webview2/code-samples-links.md # delete & redir? - - name: Getting Started tutorials href: ./webview2/get-started/get-started.md # delete & redir? displayName: GettingStartedGuides # repo dir name + - name: WebView2 sample apps + href: ./webview2/code-samples-links.md # delete & redir? + # ----------------------------------------------------------------------------- - name: Navigation, events, and authentication items: diff --git a/microsoft-edge/webview2/concepts/overview-features-apis.md b/microsoft-edge/webview2/concepts/overview-features-apis.md index 75bffa6a30..504c84ab52 100644 --- a/microsoft-edge/webview2/concepts/overview-features-apis.md +++ b/microsoft-edge/webview2/concepts/overview-features-apis.md @@ -2986,6 +2986,7 @@ Use the following APIs to forward `IDropTarget` events from the system to the We --- + #### Accessibility diff --git a/microsoft-edge/webview2/get-started/get-started.md b/microsoft-edge/webview2/get-started/get-started.md index c64c0190a0..d37716affa 100644 --- a/microsoft-edge/webview2/get-started/get-started.md +++ b/microsoft-edge/webview2/get-started/get-started.md @@ -10,7 +10,8 @@ ms.date: 02/22/2023 --- # Getting Started tutorials -These articles cover how to set up your development tools and create an initial WebView2 app, like a Hello World app with basic functionality. Learn about WebView2 concepts along the way. +These articles cover how to set up your development tools and create an initial WebView2 app, like a Hello World app with basic functionality. You learn WebView2 concepts along the way. If you want to run a sample first, see [Win32 sample app](../samples/webview2apissample.md) or another sample app article. + | Article | Completed project | Description | |---|---|---| diff --git a/microsoft-edge/webview2/get-started/hololens2.md b/microsoft-edge/webview2/get-started/hololens2.md index 9201ac351b..b9aa9a0c41 100644 --- a/microsoft-edge/webview2/get-started/hololens2.md +++ b/microsoft-edge/webview2/get-started/hololens2.md @@ -12,6 +12,8 @@ ms.date: 11/25/2024 This tutorial is for developers using WebView2 in immersive HoloLens 2 Unity applications. +This article is to learn to write your own WebView2 code. If you want to run a sample first, see [Win32 sample app](../samples/webview2apissample.md) or another sample app article. + > [!IMPORTANT] > WebView2 on Hololens 2 continues to be available. However, support for WebView2 on Hololens 2 is discontinued; there are no planned bug fixes or content updates, and technical support has ended. Applications that use WebView2 on Hololens 2 are not guaranteed to continue to work. @@ -409,195 +411,6 @@ public class WebViewExample : MonoBehaviour, IWithPostMessage ``` - -## Additional considerations for WebView2 on HoloLens 2 - - - -#### Limitations and known issues - -When developing a HoloLens 2 Unity app with WebView2, be aware of some limitations and known issues: - -* **Pop-ups**: Pop-ups don't work well within WebView2 inside Unity apps on HoloLens 2, but they work fine in 2D XAML apps on the device. Avoid pop-ups and use alternative techniques or UI designs, such as custom pop-up-like elements within the WebView using HTML, CSS, and JavaScript. - -* **New windows**: WebView2 instances on HoloLens 2 navigate within the same window by default, unlike on Desktop. Follow this default behavior for a better user experience. Additionally, the DevTools window cannot be launched. - -* **Enterprise authentication**: Automatic Single Sign-On (SSO) leveraging OS-level tokens is currently not supported in WebView2 on HoloLens 2. Users can still sign in by providing credentials, except for cases requiring device-level authentication. Cookie storage works as expected. - -* **User interactions**: Unlike native HoloLens 2 slates, WebView2 is best interacted with by using far-interaction hand rays. Touch-to-swipe and scroll interactions might not be supported. - -* **Performance**: Complex websites with heavy use of JavaScript or advanced rendering may impact system performance or the host application's framerate. For general performance-related limitations and recommendations, see [Understanding performance for mixed reality](/windows/mixed-reality/develop/advanced-concepts/understanding-performance-for-mixed-reality) in the mixed reality documentation. Also see [Performance optimization](#performance-optimization), below. - - - -#### Performance optimization - -Optimizing the performance of WebView2 in your HoloLens 2 Unity app is crucial for a smooth user experience. Here are some recommendations: - -* **Limit the number of WebView2 instances**: We suggest using only one instance of WebView2 within a Unity app. Reuse the same instance or tear down and create a new one as needed. Keep in mind that removing the WebView prefab from the scene might not destroy the underlying WebView2 instance. You must call the `Destroy()` method on the game object to destroy it properly. - -* **Apply general Unity optimization techniques**: To optimize WebView2 performance, use the standard Unity optimization approaches, such as occlusion culling or limiting the update rate. For more information, see [Performance recommendations for Unity](/windows/mixed-reality/develop/unity/performance-recommendations-for-unity?tabs=openxr) in the mixed reality documentation. - -* **Profile and monitor WebView2 performance**: There are several ways to profile the performance of a HoloLens 2 Unity application: - - * **Unity Profiler**: A built-in tool in Unity that allows you to measure and optimize the performance of your application on various platforms, including HoloLens 2. - - * **Visual Profiler**: A feature of the Mixed Reality Toolkit that provides an in-application view of your application's performance. - - * **PIX**: A performance tuning and debugging tool for Windows that can also be used to profile Unity applications on HoloLens 2. - - - -#### Navigation - -In [Step 7 - Extending WebView2 functionality](#step-7---extending-webview2-functionality), we touched on some navigation methods. In this section, we'll expand on what we learned. - -See also: -* [WebView2 API Reference](../webview2-api-reference.md) -* [API Reference for Mixed Reality WebView plugin](/windows/mixed-reality/develop/advanced-concepts/webview2-unity-plugin) - for HoloLens 2 in the WebView2 Unity plugin. - - - - -###### IWebView interface - - - -The `IWebView` interface exposes a few methods, events, and properties related to page navigation. The main functionality exposed here is the ability to navigate to a given URL, by using `Load(Uri url)`: - -```C# -public interface IWebView -{ - // Non-navigation methods are removed for clarity. - - event WebView_OnNavigated Navigated; - - Uri Page { get; } - - void Load(Uri url); - - void Reload(bool ignoreCache); -} -``` - - - -###### IWithBrowserHistory interface - -The `IWithBrowserHistory` interface exposes a few methods and events related to page navigation. This mainly allows developers to navigate forward and backward, as you would expect with a typical web-browsing experience: - -```C# -public interface IWithBrowserHistory : IWebView -{ - // Non-navigation methods are removed for clarity. - - event WebView_OnCanGoForwardUpdated CanGoForwardUpdated; - - event WebView_OnCanGoBackUpdated CanGoBackUpdated; - - void GoBack(); - - void GoForward(); -} -``` - - - -###### SetVirtualHostNameToFolderMapping and SetVirtualHostMapping - -The [CoreWebView2.SetVirtualHostNameToFolderMapping Method](/dotnet/api/microsoft.web.webview2.core.corewebview2.setvirtualhostnametofoldermapping) enables mapping between a virtual host name and a folder path, making it accessible to websites using that host name. This method maps a local domain name to a local folder, so that the WebView2 control loads content from the specified local folder when attempting to access a resource for that domain. - -The WebView plugin for Unity exposes this functionality through the `IWithVirtualHost` interface, which has a single method, `SetVirtualHostMapping(string hostName, string folderPath)`: - -```C# -public interface IWithVirtualHost : IWebView -{ - void SetVirtualHostMapping(string hostName, string folderPath); -} -``` - -To use the `SetVirtualHostMapping` method, set `hostName` to any valid URL conforming string, such as `webview2.sample`. `folderPath` can be an absolute path or a path relative to the application's working directory, such as `Assets\Html`. - -Assuming we have an HTML file called `demo.html` under `Assets\Html`, the following code snippet demonstrates loading `demo.html` by using the WebView plugin for Unity: - -```C# -using Microsoft.MixedReality.WebView; - -public class WebViewExample : MonoBehaviour -{ - private void Start() - { - var webViewComponent = gameObject.GetComponent(); - - webViewComponent.GetWebViewWhenReady((IWebView webView) => - { - ((IWithVirtualHost)webView).SetVirtualHostMapping("webview2.sample", "Assets\\Html"); - - // Navigate to our local content. - webViewComponent.Load(new Uri("http://webview2.sample/demo.html")); - }); - } -} -``` - - - -#### Input - -There are various ways to handle input in Unity for mixed reality applications. - -* [Input overview — MRTK2](/windows/mixed-reality/mrtk-unity/mrtk2/features/input/overview) - recommended for Mixed Reality Toolkit 2.8 applications. -* [Input — MRTK3](/windows/mixed-reality/mrtk-unity/mrtk3-input/packages/input/overview) - recommended for Mixed Reality Toolkit 3 applications. -* [Unity Input System](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.5/manual/index.html) - -Regardless of the input system used within your Unity application, interop code between the various application input events and the WebView plugin for Unity is required. This means translating those events (such as Pointer events) into a `WebViewMouseEventData` object and then forwarding those events to the plugin via the `IWithMouseEvent` interface: - -```C# -public interface IWithMouseEvents : IWithInputEvents -{ - void MouseEvent(WebViewMouseEventData mouseEvent); -} -``` - -WebView2 is unaware of Unity's input system and likely has a different coordinate system than your Unity scene. As a result, when there is a pointer-down event, its coordinates must be translated into the coordinate system of the WebView2 control. Additionally, the pointer-down event needs to be converted into an appropriate `WebViewMouseEventData` event type. - -Simple example: - -```C# -using Microsoft.MixedReality.WebView; - -public class WebViewExample : MonoBehaviour, IPointerDownHandler -{ - // WebView setup steps skipped for brevity - - public void OnPointerDown(PointerEventData eventData) - { - IWithMouseEvents mouseEventsWebView = webView as IWithMouseEvents; - - // Call hypothetical function which converts the event's x, y into the WebView2's coordinate space. - var hitCoord = ConvertToWebViewSpace(eventData.position.x, eventData.position.y); - - WebViewMouseEventData mouseEvent = new WebViewMouseEventData - { - X = hitCoord.x, - Y = hitCoord.y, - Type = WebViewMouseEventData.EventType.MouseDown, - Button = WebViewMouseEventData.MouseButton.ButtonLeft, - TertiaryAxisDeviceType = WebViewMouseEventData.TertiaryAxisDevice.PointingDevice - }; - - // Propagate the event to the WebView plugin. - mouseEventsWebView.MouseEvent(mouseEvent); - } -} -``` - -In the above example, pointer-down events are converted into `WebViewMouseEventData` objects and forwarded to the WebView plugin for Unity. It is essentially converted into a mouse-down event. In order to create mouse click events, pointer-up events would need to be handled in a similar fashion. - -In the example above, `ConvertToWebViewSpace` is intentionally not implemented. - - ## See also diff --git a/microsoft-edge/webview2/get-started/win32.md b/microsoft-edge/webview2/get-started/win32.md index ec78a36119..3710e4aa7c 100644 --- a/microsoft-edge/webview2/get-started/win32.md +++ b/microsoft-edge/webview2/get-started/win32.md @@ -12,6 +12,8 @@ ms.date: 07/29/2022 +This article is to learn to write your own WebView2 code. If you want to run a sample first, see [Win32 sample app](../samples/webview2apissample.md) or another sample app article. + In this article, you set up your development tools (if not done already), learn how to add WebView2 code to a Win32 app project, and learn about WebView2 concepts along the way. This tutorial starts by opening an existing Win32 app project that has WebView2 code added. The project uses the [Win32_GettingStarted (WebView2GettingStarted.sln)](https://github.com/MicrosoftEdge/WebView2Samples/tree/main/GettingStartedGuides/Win32_GettingStarted) directory that's part of the `WebView2Samples` repo. To use this article, you do the following: diff --git a/microsoft-edge/webview2/get-started/winforms.md b/microsoft-edge/webview2/get-started/winforms.md index cb36566e5c..9c128c0815 100644 --- a/microsoft-edge/webview2/get-started/winforms.md +++ b/microsoft-edge/webview2/get-started/winforms.md @@ -10,6 +10,8 @@ ms.date: 10/26/2022 --- # Get started with WebView2 in WinForms apps +This article is to learn to write your own WebView2 code. If you want to run a sample first, see [Win32 sample app](../samples/webview2apissample.md) or another sample app article, such as [WinForms sample app](../samples/webview2windowsformsbrowser.md). + -## WinAppSDK supports custom WebView2 environments - -WinAppSDK supports custom WebView2 environments, starting with WinAppSDK 1.5 ([1.5.0-experimental2](/windows/apps/windows-app-sdk/experimental-channel#version-15-experimental-150-experimental2)). For more information, see [WinUI3 WebView2 with a custom CoreWebView2Environment](https://github.com/microsoft/microsoft-ui-xaml/issues/6150). - -To instantiate a custom WebView2 environment, you could initialize WebView2 with one of the overrides of `WebView2.EnsureCoreWebView2Async` (listed below), and pass in your custom `CoreWebView2Environment` (and, optionally, custom `CoreWebView2ControllerOptions`): - -```csharp -public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment) -public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment, CoreWebView2ControllerOptions controllerOptions) -``` - -Also see the example code in [Disabling SmartScreen navigation](#disabling-smartscreen-navigation), below. - -API Reference: -* [WebView2.EnsureCoreWebView2Async](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2.ensurecorewebview2async) -* [CoreWebView2ControllerOptions](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controlleroptions) -* [CoreWebView2Environment](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment) -* [CoreWebView2EnvironmentOptions](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environmentoptions) - - - -## WinUI 3 WebView2 special considerations - - - -#### Disabling SmartScreen navigation - -WebView2 sends URLs that are navigated to in your application to the [SmartScreen](/windows/security/threat-protection/microsoft-defender-smartscreen/microsoft-defender-smartscreen-overview) service, to ensure that your customers stay secure. If you want to disable this navigation, use a custom `CoreWebView2Environment`, as follows: - -```csharp -CoreWebView2EnvironmentOptions environmentOptions = new CoreWebView2EnvironmentOptions(); -environmentOptions.AdditionalBrowserArguments = "--disable-features=msSmartScreenProtection"; - -string browserFolder = null; // Use null to get default browser folder -string userDataFolder = null; // Use null to get default user data folder -CoreWebView2Environment environment = await CoreWebView2Environment.CreateWithOptionsAsync( - browserFolder, userDataFolder, environmentOptions); - -// ... - -this.WebView2.EnsureCoreWebView2Async(environment); -``` - - - -###### Disabling SmartScreen by using an environment variable - -We no longer recommend using an environment variable. Use the above API code-based approach instead. - -* `Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");` - -This environment variable must be set prior to `CoreWebView2` creation, which occurs when the [WebView2.Source property](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2.source#microsoft-ui-xaml-controls-webview2-source) is initially set or the [WebView2.EnsureCoreWebView2Async method](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2.ensurecorewebview2async#microsoft-ui-xaml-controls-webview2-ensurecorewebview2async) is initially called. - - - -#### Setting DefaultBackgroundColor - -In WebView2 for WinUI 3, the `DefaultBackgroundColor` setting exists on the WebView2 XAML object. For example: - -```csharp -public MainWindow() -{ - this.InitializeComponent(); - MyWebView.DefaultBackgroundColor = Colors.LightBlue; -} -``` - - - -#### Transparency - -WinUI 3 doesn't support transparent backgrounds. See [Transparent background support for WebView2? · Issue #2992](https://github.com/microsoft/microsoft-ui-xaml/issues/2992). - - - -#### WinAppSDK support for custom WebView2 environments - -See [WinAppSDK supports custom WebView2 environments](#winappsdk-supports-custom-webview2-environments), above. - - ## See also + * [WebView2 API Reference](../webview2-api-reference.md) * [Introduction to Microsoft Edge WebView2](../index.md) - overview of features. @@ -603,7 +525,7 @@ See [WinAppSDK supports custom WebView2 environments](#winappsdk-supports-custom * [Development best practices for WebView2 appsDevelopment best practices](../concepts/developer-guide.md) developer.microsoft.com: -* [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2) - initial introduction to WebView2 features at developer.microsoft.com. +* [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2) - initial introduction to WebView2 features. GitHub: * [Getting Started with WebView2 in WinUI3](https://github.com/MicrosoftEdge/WebView2Samples/tree/main/GettingStartedGuides/WinUI3_GettingStarted#readme) diff --git a/microsoft-edge/webview2/get-started/winui2.md b/microsoft-edge/webview2/get-started/winui2.md index 23cc62d193..cfb248d41c 100644 --- a/microsoft-edge/webview2/get-started/winui2.md +++ b/microsoft-edge/webview2/get-started/winui2.md @@ -10,6 +10,8 @@ ms.date: 10/31/2023 --- # Get started with WebView2 in WinUI 2 (UWP) apps +This article is to learn to write your own WebView2 code. If you want to run a sample first, see [Win32 sample app](../samples/webview2apissample.md) or another sample app article, such as [WinUI 2 (UWP) sample app](../samples/webview2_sample_uwp.md). + In this tutorial, you: * Set up your development tools for creating UWP apps that use WebView2 to display web content. * Create an initial WinUI 2 (UWP) app. @@ -61,7 +63,8 @@ Only a subset of WebView2 interfaces/functions are exposed in WinUI: * Interfaces such as `CoreWebView2Controller` are hidden, because WinUI takes care of the environment and window creation behind the scenes. -See also [XAML limitation](#xaml-limitation) below. +See also: +* [XAML limitation](../platforms/winui2-uwp.md#xaml-limitation) in _WebView2 in WinUI 2 (UWP) apps_. @@ -296,191 +299,22 @@ Next, learn about navigation events, which are essential for WebView2 apps. The * In a new window or tab, read [Navigation events for WebView2 apps](../concepts/navigation-events.md), and then return to this page. - -## Special considerations for WebView2 on WinUI 2 (UWP) - -The WebView2 WinUI 2 (UWP) control is in development. - - - -#### Autofill UI - -Autofill UI is not implemented yet for WebView2 for UWP apps. - -See also: -* [Autofill](../concepts/overview-features-apis.md#autofill) in _Overview of WebView2 APIs_. - - - -#### Print to PDF - -Print to PDF requires that the app have access to a writeable location in UWP, such as a local folder. For a full list of UWP-accessible paths, see [File access permissions](/windows/uwp/files/file-access-permissions). - -See also: -* [Printing](../concepts/overview-features-apis.md#printing) in _Overview of WebView2 APIs_. - - - -#### Default printing - -Default printing is disabled for WebView2 for UWP apps. However, you can capture and print the current viewport, by calling `CapturePreview`. - -See also: -* [Image capture](../concepts/overview-features-apis.md#image-capture) in _Overview of WebView2 APIs_. - - - -#### SmartScreen - -WebView2 sends URLs that are navigated to in your application to the [SmartScreen](/windows/security/threat-protection/microsoft-defender-smartscreen/microsoft-defender-smartscreen-overview) service, to ensure that your customers stay secure. If you want to disable this navigation, you can do so via an environment variable: - -* `Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");` - -This environment variable must be set prior to `CoreWebView2` creation, which occurs when the [WebView2.Source property](/windows/winui/api/microsoft.ui.xaml.controls.webview2.source) is initially set or the [WebView2.EnsureCoreWebView2Async method](/windows/winui/api/microsoft.ui.xaml.controls.webview2.ensurecorewebview2async) is initially called. - - - -#### Downloading files - -There are a couple of known limitations for current downloads behavior for WebView2 in UWP. - -###### Save As - -Saving files via **Save As** is working and is enabled for WebView2 for UWP apps. The files will be saved in the folder that the user selects. - -###### Which folder the files are downloaded to - -If the host doesn't change the `ResultFilePath` of the downloaded file, the downloaded files will be downloaded to a subfolder with the app package's name in the `Downloads` folder. - -If the host changes the `ResultFilePath` of the downloaded file, the file will only be downloaded if the app has access to that file path by default. If you want to use a file location that the app doesn't have access to by default, you must set the corresponding capability. See [App capability declarations](/windows/uwp/packaging/app-capability-declarations) in the UWP documentation. - -###### Downloads Hub - -Opening files and folders from the Downloads Hub is disabled. Clicking on the file or folder icon won't open the respective file/folder. - -See also: -* [Downloads](../concepts/overview-features-apis.md#downloads) in _Overview of WebView2 APIs_. - - - -#### XAML limitation - -XAML Island support requires additional work and may be considered for future releases. - - - -#### Setting DefaultBackgroundColor - -On WinUI 2, the `DefaultBackgroundColor` property is not exposed directly. You can set the default background color by setting an environment variable, as follows: - -```csharp -Environment.SetEnvironmentVariable("WEBVIEW2_DEFAULT_BACKGROUND_COLOR", "FF000000"); -``` - -See also: -* .NET: [WebView2.DefaultBackgroundColor Property](/dotnet/api/microsoft.web.webview2.winforms.webview2.defaultbackgroundcolor) -* Win32: [ICoreWebView2Controller2::DefaultBackgroundColor property (get](/microsoft-edge/webview2/reference/win32/icorewebview2controller2#get_defaultbackgroundcolor), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2controller2#put_defaultbackgroundcolor) - - - -#### Setting transparency - -On WinUI 2, transparency is achieved by setting the color to `00FFFFFF`. - - - -#### CSS cursors - -On WinUI 2 (UWP), CSS cursors have the following limitations. - - -###### Image URLs - -The CSS cursor cannot be an image URL, such as `cursor: url(https://contoso.com/cursor.png), pointer;`. See [CSS - cursor loaded from URL doesn't work](https://github.com/MicrosoftEdge/WebView2Feedback/issues/1925). - - -###### Predefined CSS cursors - -On WinUI 2 (UWP), some of the predefined CSS cursors are not supported. You can use CSS cursors to change the cursor to some of the predefined cursors, such as `cursor: wait;` or `cursor: crosshair;`, but not to others, such as `cursor: progress` or `cursor: none`. - -| Keyword | Supported? | -|---|:---:| -| **General** | | -| auto | ✔️ | -| default | ✔️ | -| none | ❌ | -| **Links & status** | | -| context-menu | ✔️ | -| help | ✔️ | -| pointer | ✔️ | -| progress | ❌ | -| wait | ✔️ | -| **Selection** | | -| cell | ❌ | -| crosshair | ✔️ | -| text | ✔️ | -| vertical-text | ❌ | -| **Drag & drop** | | -| alias | ❌ | -| copy | ❌ | -| move | ✔️ | -| no-drop | ✔️ | -| not-allowed | ✔️ | -| grab | ❌ | -| grabbing | ❌ | -| **Resizing & scrolling** | | -| all-scroll | ✔️ | -| col-resize | ❌ | -| row-resize | ❌ | -| n-resize | ✔️ | -| e-resize | ✔️ | -| s-resize | ✔️ | -| w-resize | ✔️ | -| ne-resize | ✔️ | -| nw-resize | ✔️ | -| se-resize | ✔️ | -| sw-resize | ✔️ | -| ew-resize | ✔️ | -| ns-resize | ✔️ | -| nesw-resize | ✔️ | -| nwse-resize | ✔️ | -| **Zooming** | | -| zoom-in | ❌ | -| zoom-out | ❌ | - -See also: -* [CSS cursors](https://developer.mozilla.org/docs/Web/CSS/cursor#values) - the **Values** section describes the above keyword values. - - - - -#### Microsoft Edge Developer Tools - -On WinUI 2, Microsoft Edge DevTools cannot be launched inside a store-signed WebView2 WinUI 2 (UWP) app. However, you can work around this by using remote debugging. See [Remote debugging WebView2 WinUI 2 (UWP) apps](../how-to/remote-debugging.md). - - - -#### API limitations - -The following classes aren't accessible in WinUI 2: - -* `CoreWebView2EnvironmentOptions` -* `CoreWebView2ControllerOptions` - - ## See also +* [WebView2 in WinUI 2 (UWP) apps](../platforms/winui2-uwp.md) * [WebView2 API Reference](../webview2-api-reference.md) -* [WinUI 2 (UWP) sample app](../samples/webview2_sample_uwp.md) - steps to download, update, build, and run the WinUI 2 WebView2 sample. -* [Manage user data folders](../concepts/user-data-folder.md) -* [WebView2 sample apps](../code-samples-links.md) - a guide to the `WebView2Samples` repo. * [Development best practices for WebView2 apps](../concepts/developer-guide.md) + * [Manage user data folders](../concepts/user-data-folder.md) +* [WebView2 sample apps](../code-samples-links.md) - a guide to the `WebView2Samples` repo. + * [WinUI 2 (UWP) sample app](../samples/webview2_sample_uwp.md) - steps to download, update, build, and run the WinUI 2 WebView2 sample. +* Get Started tutorial finished project: Unlike some of the other tutorials, there isn't a completed version of this Getting Started tutorial in the WebView2Samples repo. GitHub: * [WebView2Samples repo](https://github.com/MicrosoftEdge/WebView2Samples) * [WebView2 UWP Sample App](https://github.com/MicrosoftEdge/WebView2Samples/tree/main/SampleApps/webview2_sample_uwp) - the WinUI 2 (UWP) WebView2 sample. * [Issues - microsoft-ui-xaml repo](https://github.com/microsoft/microsoft-ui-xaml/issues) - to enter WinUI-specific feature requests or bugs. -* Unlike some of the other tutorials, there isn't a completed version of this Getting Started tutorial in the WebView2Samples repo. -* [Microsoft.UI.Xaml NuGet package](https://www.nuget.org/packages/Microsoft.UI.Xaml/) * [Media App Samples for Xbox](https://github.com/microsoft/Media-App-Samples-for-Xbox) + +NuGet: +* [Microsoft.UI.Xaml NuGet package](https://www.nuget.org/packages/Microsoft.UI.Xaml/) diff --git a/microsoft-edge/webview2/get-started/wpf.md b/microsoft-edge/webview2/get-started/wpf.md index 1b919119e4..254e981314 100644 --- a/microsoft-edge/webview2/get-started/wpf.md +++ b/microsoft-edge/webview2/get-started/wpf.md @@ -10,6 +10,8 @@ ms.date: 09/19/2022 --- # Get started with WebView2 in WPF apps +This article is to learn to write your own WebView2 code. If you want to run a sample first, see [Win32 sample app](../samples/webview2apissample.md) or another sample app article, such as [WPF sample app](../samples/webview2wpfbrowser.md). + This article covers how to set up your development tools and create an initial WebView2 app for Windows Presentation Foundation (WPF), and learn about WebView2 concepts along the way. In this tutorial, you use the **WPF Application** or **WPF App (.NET Framework)** project template to create a WPF app, and then install the WebView2 SDK for the project to add WebView2. diff --git a/microsoft-edge/webview2/index.md b/microsoft-edge/webview2/index.md index fb889ef39f..b23e191b3c 100644 --- a/microsoft-edge/webview2/index.md +++ b/microsoft-edge/webview2/index.md @@ -132,7 +132,7 @@ developer.microsoft.com: * [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2) - initial introduction to WebView2 features at developer.microsoft.com. Microsoft.com: -* [Become a Microsoft Edge Insider](https://www.microsoft.com/en-us/edge/download/insider) - download the preview channels of Microsoft Edge (Canary, Dev, and Beta). +* [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider) - download the preview channels of Microsoft Edge (Canary, Dev, and Beta). YouTube: * [Building, Deploying, and Managing WebView2 Applications](https://www.youtube.com/watch?v=LX-eXvcSx6c) - March 2, 2021. diff --git a/microsoft-edge/webview2/platforms/hololens-2-unity.md b/microsoft-edge/webview2/platforms/hololens-2-unity.md new file mode 100644 index 0000000000..db7f12de80 --- /dev/null +++ b/microsoft-edge/webview2/platforms/hololens-2-unity.md @@ -0,0 +1,229 @@ +--- +title: WebView2 in HoloLens 2 Unity apps +description: How to include a WebView2 control within your immersive HoloLens 2 Unity app. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 01/24/2025 +--- +# WebView2 in HoloLens 2 Unity apps + +This article is for developers using WebView2 in immersive HoloLens 2 Unity applications. + +> [!IMPORTANT] +> WebView2 on Hololens 2 continues to be available. However, support for WebView2 on Hololens 2 is discontinued; there are no planned bug fixes or content updates, and technical support has ended. Applications that use WebView2 on Hololens 2 are not guaranteed to continue to work. + +WebView2 on HoloLens 2 and the WebView plugin for Unity are both in Preview and are subject to change before general availability. + +WebView2 only works on HoloLens 2 devices running the Windows 11 update. For more information, see [Update HoloLens 2](/hololens/hololens-update-hololens). + +For WebView2-enabled 2D applications on HoloLens 2, see [Get started with WebView2 in WinUI 2 (UWP) apps](../get-started/winui2.md). + + + +## Limitations and known issues + +When developing a HoloLens 2 Unity app with WebView2, be aware of some limitations and known issues: + +* **Pop-ups**: Pop-ups don't work well within WebView2 inside Unity apps on HoloLens 2, but they work fine in 2D XAML apps on the device. Avoid pop-ups and use alternative techniques or UI designs, such as custom pop-up-like elements within the WebView using HTML, CSS, and JavaScript. + +* **New windows**: WebView2 instances on HoloLens 2 navigate within the same window by default, unlike on Desktop. Follow this default behavior for a better user experience. Additionally, the DevTools window cannot be launched. + +* **Enterprise authentication**: Automatic Single Sign-On (SSO) leveraging OS-level tokens is currently not supported in WebView2 on HoloLens 2. Users can still sign in by providing credentials, except for cases requiring device-level authentication. Cookie storage works as expected. + +* **User interactions**: Unlike native HoloLens 2 slates, WebView2 is best interacted with by using far-interaction hand rays. Touch-to-swipe and scroll interactions might not be supported. + +* **Performance**: Complex websites with heavy use of JavaScript or advanced rendering may impact system performance or the host application's framerate. For general performance-related limitations and recommendations, see [Understanding performance for mixed reality](/windows/mixed-reality/develop/advanced-concepts/understanding-performance-for-mixed-reality) in the mixed reality documentation. Also see [Performance optimization](#performance-optimization), below. + + + +## Performance optimization + +Optimizing the performance of WebView2 in your HoloLens 2 Unity app is crucial for a smooth user experience. Here are some recommendations: + +* **Limit the number of WebView2 instances**: We suggest using only one instance of WebView2 within a Unity app. Reuse the same instance or tear down and create a new one as needed. Keep in mind that removing the WebView prefab from the scene might not destroy the underlying WebView2 instance. You must call the `Destroy()` method on the game object to destroy it properly. + +* **Apply general Unity optimization techniques**: To optimize WebView2 performance, use the standard Unity optimization approaches, such as occlusion culling or limiting the update rate. For more information, see [Performance recommendations for Unity](/windows/mixed-reality/develop/unity/performance-recommendations-for-unity?tabs=openxr) in the mixed reality documentation. + +* **Profile and monitor WebView2 performance**: There are several ways to profile the performance of a HoloLens 2 Unity application: + + * **Unity Profiler**: A built-in tool in Unity that allows you to measure and optimize the performance of your application on various platforms, including HoloLens 2. + + * **Visual Profiler**: A feature of the Mixed Reality Toolkit that provides an in-application view of your application's performance. + + * **PIX**: A performance tuning and debugging tool for Windows that can also be used to profile Unity applications on HoloLens 2. + + + +## Navigation + +Some navigation methods are demonstrated in [Step 7 - Extending WebView2 functionality](../get-started/hololens2.md#step-7---extending-webview2-functionality) in _Get started with WebView2 in HoloLens 2 Unity apps (Preview)_. The present section expands on that demonstration. + +See also: +* [WebView2 API Reference](../webview2-api-reference.md) +* [API Reference for Mixed Reality WebView plugin](/windows/mixed-reality/develop/advanced-concepts/webview2-unity-plugin) - for HoloLens 2 in the WebView2 Unity plugin. + + + +#### IWebView interface + + + +The `IWebView` interface exposes a few methods, events, and properties related to page navigation. The main functionality exposed here is the ability to navigate to a given URL, by using `Load(Uri url)`: + +```C# +public interface IWebView +{ + // Non-navigation methods are removed for clarity. + + event WebView_OnNavigated Navigated; + + Uri Page { get; } + + void Load(Uri url); + + void Reload(bool ignoreCache); +} +``` + + + +#### IWithBrowserHistory interface + +The `IWithBrowserHistory` interface exposes a few methods and events related to page navigation. This mainly allows developers to navigate forward and backward, as you would expect with a typical web-browsing experience: + +```C# +public interface IWithBrowserHistory : IWebView +{ + // Non-navigation methods are removed for clarity. + + event WebView_OnCanGoForwardUpdated CanGoForwardUpdated; + + event WebView_OnCanGoBackUpdated CanGoBackUpdated; + + void GoBack(); + + void GoForward(); +} +``` + + + +#### SetVirtualHostNameToFolderMapping and SetVirtualHostMapping + +The [CoreWebView2.SetVirtualHostNameToFolderMapping Method](/dotnet/api/microsoft.web.webview2.core.corewebview2.setvirtualhostnametofoldermapping) enables mapping between a virtual host name and a folder path, making it accessible to websites using that host name. This method maps a local domain name to a local folder, so that the WebView2 control loads content from the specified local folder when attempting to access a resource for that domain. + +The WebView plugin for Unity exposes this functionality through the `IWithVirtualHost` interface, which has a single method, `SetVirtualHostMapping(string hostName, string folderPath)`: + +```C# +public interface IWithVirtualHost : IWebView +{ + void SetVirtualHostMapping(string hostName, string folderPath); +} +``` + +To use the `SetVirtualHostMapping` method, set `hostName` to any valid URL conforming string, such as `webview2.sample`. `folderPath` can be an absolute path or a path relative to the application's working directory, such as `Assets\Html`. + +Assuming we have an HTML file called `demo.html` under `Assets\Html`, the following code snippet demonstrates loading `demo.html` by using the WebView plugin for Unity: + +```C# +using Microsoft.MixedReality.WebView; + +public class WebViewExample : MonoBehaviour +{ + private void Start() + { + var webViewComponent = gameObject.GetComponent(); + + webViewComponent.GetWebViewWhenReady((IWebView webView) => + { + ((IWithVirtualHost)webView).SetVirtualHostMapping("webview2.sample", "Assets\\Html"); + + // Navigate to our local content. + webViewComponent.Load(new Uri("http://webview2.sample/demo.html")); + }); + } +} +``` + + + +## Input + +There are various ways to handle input in Unity for mixed reality applications. + +* [Input overview — MRTK2](/windows/mixed-reality/mrtk-unity/mrtk2/features/input/overview) - recommended for Mixed Reality Toolkit 2.8 applications. +* [Input — MRTK3](/windows/mixed-reality/mrtk-unity/mrtk3-input/packages/input/overview) - recommended for Mixed Reality Toolkit 3 applications. +* [Unity Input System](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.5/manual/index.html) + +Regardless of the input system used within your Unity application, interop code between the various application input events and the WebView plugin for Unity is required. This means translating those events (such as Pointer events) into a `WebViewMouseEventData` object and then forwarding those events to the plugin via the `IWithMouseEvent` interface: + +```C# +public interface IWithMouseEvents : IWithInputEvents +{ + void MouseEvent(WebViewMouseEventData mouseEvent); +} +``` + +WebView2 is unaware of Unity's input system and likely has a different coordinate system than your Unity scene. As a result, when there is a pointer-down event, its coordinates must be translated into the coordinate system of the WebView2 control. Additionally, the pointer-down event needs to be converted into an appropriate `WebViewMouseEventData` event type. + +Simple example: + +```C# +using Microsoft.MixedReality.WebView; + +public class WebViewExample : MonoBehaviour, IPointerDownHandler +{ + // WebView setup steps skipped for brevity + + public void OnPointerDown(PointerEventData eventData) + { + IWithMouseEvents mouseEventsWebView = webView as IWithMouseEvents; + + // Call hypothetical function which converts the event's x, y into the WebView2's coordinate space. + var hitCoord = ConvertToWebViewSpace(eventData.position.x, eventData.position.y); + + WebViewMouseEventData mouseEvent = new WebViewMouseEventData + { + X = hitCoord.x, + Y = hitCoord.y, + Type = WebViewMouseEventData.EventType.MouseDown, + Button = WebViewMouseEventData.MouseButton.ButtonLeft, + TertiaryAxisDeviceType = WebViewMouseEventData.TertiaryAxisDevice.PointingDevice + }; + + // Propagate the event to the WebView plugin. + mouseEventsWebView.MouseEvent(mouseEvent); + } +} +``` + +In the above example, pointer-down events are converted into `WebViewMouseEventData` objects and forwarded to the WebView plugin for Unity. It is essentially converted into a mouse-down event. In order to create mouse click events, pointer-up events would need to be handled in a similar fashion. + +In the example above, `ConvertToWebViewSpace` is intentionally not implemented. + + + +## See also + + +* [Get started with WebView2 in WinUI 2 (UWP) apps](../get-started/winui2.md) + +API Reference: +* [WebView2 API Reference](../webview2-api-reference.md) +* [CoreWebView2.SetVirtualHostNameToFolderMapping Method](/dotnet/api/microsoft.web.webview2.core.corewebview2.setvirtualhostnametofoldermapping) + +Hololens docs: +* [Update HoloLens 2](/hololens/hololens-update-hololens) + +Mixed Reality docs: +* [Understanding performance for mixed reality](/windows/mixed-reality/develop/advanced-concepts/understanding-performance-for-mixed-reality) +* [Performance recommendations for Unity](/windows/mixed-reality/develop/unity/performance-recommendations-for-unity?tabs=openxr) +* [API Reference for Mixed Reality WebView plugin](/windows/mixed-reality/develop/advanced-concepts/webview2-unity-plugin) +* [Input overview — MRTK2](/windows/mixed-reality/mrtk-unity/mrtk2/features/input/overview) +* [Input — MRTK3](/windows/mixed-reality/mrtk-unity/mrtk3-input/packages/input/overview) + +Unity docs: +* [Unity Input System](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.5/manual/index.html) diff --git a/microsoft-edge/webview2/platforms/win32.md b/microsoft-edge/webview2/platforms/win32.md new file mode 100644 index 0000000000..cf6842892d --- /dev/null +++ b/microsoft-edge/webview2/platforms/win32.md @@ -0,0 +1,19 @@ +--- +title: WebView2 in Win32 apps +description: How to include a WebView2 control within your Win32 app. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 01/24/2025 +--- +# WebView2 in Win32 apps + +The main sample for WebView2 is for Win32. + +Articles: +* [Win32 sample app](../samples/webview2apissample.md) +* [Win32 sample app with Visual Composition](../samples/webview2samplewincomp.md) +* [Win32 sample WebView2Browser](../samples/webview2browser.md) +* [Get started with WebView2 in Win32 apps](../get-started/win32.md) diff --git a/microsoft-edge/webview2/platforms/winforms.md b/microsoft-edge/webview2/platforms/winforms.md new file mode 100644 index 0000000000..251fc53727 --- /dev/null +++ b/microsoft-edge/webview2/platforms/winforms.md @@ -0,0 +1,17 @@ +--- +title: WebView2 in WinForms apps +description: How to include a WebView2 control within your WinForms app. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 01/24/2025 +--- +# WebView2 in WinForms apps + +Articles: +* [Win32 sample app](../samples/webview2apissample.md) +* [Win32 sample app with Visual Composition](../samples/webview2samplewincomp.md) +* [Win32 sample WebView2Browser](../samples/webview2browser.md) +* [Get started with WebView2 in Win32 apps](../get-started/win32.md) diff --git a/microsoft-edge/webview2/platforms/winui2-uwp.md b/microsoft-edge/webview2/platforms/winui2-uwp.md new file mode 100644 index 0000000000..ebf94e36a2 --- /dev/null +++ b/microsoft-edge/webview2/platforms/winui2-uwp.md @@ -0,0 +1,229 @@ +--- +title: WebView2 in WinUI 2 (UWP) apps +description: How to include a WebView2 control within your WinUI 2 (UWP) app. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 01/27/2025 +--- +# WebView2 in WinUI 2 (UWP) apps + +The following considerations apply to WebView2 in WinUI 2 (UWP) apps. The WebView2 WinUI 2 (UWP) control is in development. + + + +## Autofill UI + +Autofill UI is not implemented yet for WebView2 for UWP apps. + +See also: +* [Autofill](../concepts/overview-features-apis.md#autofill) in _Overview of WebView2 APIs_. + + + +## Print to PDF + +Print to PDF requires that the app have access to a writeable location in UWP, such as a local folder. For a full list of UWP-accessible paths, see [File access permissions](/windows/uwp/files/file-access-permissions). + +See also: +* [Printing](../concepts/overview-features-apis.md#printing) in _Overview of WebView2 APIs_. + + + +## Default printing + +Default printing is disabled for WebView2 for UWP apps. However, you can capture and print the current viewport, by calling `CapturePreview`. + +See also: +* [Image capture](../concepts/overview-features-apis.md#image-capture) in _Overview of WebView2 APIs_. + + + +## SmartScreen + +WebView2 sends URLs that are navigated to in your application to the [SmartScreen](/windows/security/threat-protection/microsoft-defender-smartscreen/microsoft-defender-smartscreen-overview) service, to ensure that your customers stay secure. If you want to disable this navigation, you can do so via an environment variable: + +* `Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");` + +This environment variable must be set prior to `CoreWebView2` creation, which occurs when the [WebView2.Source property](/windows/winui/api/microsoft.ui.xaml.controls.webview2.source) is initially set or the [WebView2.EnsureCoreWebView2Async method](/windows/winui/api/microsoft.ui.xaml.controls.webview2.ensurecorewebview2async) is initially called. + + + +## Downloading files + +There are a couple of known limitations for current downloads behavior for WebView2 in UWP. + + + +#### Save As + +Saving files via **Save As** is working and is enabled for WebView2 for UWP apps. The files will be saved in the folder that the user selects. + + + +#### Which folder the files are downloaded to + +If the host doesn't change the `ResultFilePath` of the downloaded file, the downloaded files will be downloaded to a subfolder with the app package's name in the `Downloads` folder. + +If the host changes the `ResultFilePath` of the downloaded file, the file will only be downloaded if the app has access to that file path by default. If you want to use a file location that the app doesn't have access to by default, you must set the corresponding capability. See [App capability declarations](/windows/uwp/packaging/app-capability-declarations) in the UWP documentation. + + + +#### Downloads Hub + +Opening files and folders from the Downloads Hub is disabled. Clicking on the file or folder icon won't open the respective file/folder. + +See also: +* [Downloads](../concepts/overview-features-apis.md#downloads) in _Overview of WebView2 APIs_. + + + +## XAML limitation + +XAML Island support requires additional work and may be considered for future releases. + + + +## Setting DefaultBackgroundColor + +On WinUI 2, the `DefaultBackgroundColor` property is not exposed directly. You can set the default background color by setting an environment variable, as follows: + +```csharp +Environment.SetEnvironmentVariable("WEBVIEW2_DEFAULT_BACKGROUND_COLOR", "FF000000"); +``` + +See also: +* .NET: [WebView2.DefaultBackgroundColor Property](/dotnet/api/microsoft.web.webview2.winforms.webview2.defaultbackgroundcolor) +* Win32: [ICoreWebView2Controller2::DefaultBackgroundColor property (get](/microsoft-edge/webview2/reference/win32/icorewebview2controller2#get_defaultbackgroundcolor), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2controller2#put_defaultbackgroundcolor) + + + + + +## Setting transparency + +On WinUI 2, transparency is achieved by setting the color to `00FFFFFF`. + + + +## CSS cursors + +On WinUI 2 (UWP), CSS cursors have the following limitations. + + + +#### Image URLs + +The CSS cursor cannot be an image URL, such as `cursor: url(https://contoso.com/cursor.png), pointer;`. See [CSS - cursor loaded from URL doesn't work](https://github.com/MicrosoftEdge/WebView2Feedback/issues/1925). + + + +#### Predefined CSS cursors + +On WinUI 2 (UWP), some of the predefined CSS cursors are not supported. You can use CSS cursors to change the cursor to some of the predefined cursors, such as `cursor: wait;` or `cursor: crosshair;`, but not to others, such as `cursor: progress` or `cursor: none`. + +| Keyword | Supported? | +|---|:---:| +| **General** | | +| auto | ✔️ | +| default | ✔️ | +| none | ❌ | +| **Links & status** | | +| context-menu | ✔️ | +| help | ✔️ | +| pointer | ✔️ | +| progress | ❌ | +| wait | ✔️ | +| **Selection** | | +| cell | ❌ | +| crosshair | ✔️ | +| text | ✔️ | +| vertical-text | ❌ | +| **Drag & drop** | | +| alias | ❌ | +| copy | ❌ | +| move | ✔️ | +| no-drop | ✔️ | +| not-allowed | ✔️ | +| grab | ❌ | +| grabbing | ❌ | +| **Resizing & scrolling** | | +| all-scroll | ✔️ | +| col-resize | ❌ | +| row-resize | ❌ | +| n-resize | ✔️ | +| e-resize | ✔️ | +| s-resize | ✔️ | +| w-resize | ✔️ | +| ne-resize | ✔️ | +| nw-resize | ✔️ | +| se-resize | ✔️ | +| sw-resize | ✔️ | +| ew-resize | ✔️ | +| ns-resize | ✔️ | +| nesw-resize | ✔️ | +| nwse-resize | ✔️ | +| **Zooming** | | +| zoom-in | ❌ | +| zoom-out | ❌ | + +See also: +* [CSS cursors](https://developer.mozilla.org/docs/Web/CSS/cursor#values) - the **Values** section describes the above keyword values. + + + + +## Microsoft Edge Developer Tools + +On WinUI 2, Microsoft Edge DevTools cannot be launched inside a store-signed WebView2 WinUI 2 (UWP) app. However, you can work around this by using remote debugging. See [Remote debugging WebView2 WinUI 2 (UWP) apps](../how-to/remote-debugging.md). + + + +## API limitations + +The following classes aren't accessible in WinUI 2: + +* `CoreWebView2EnvironmentOptions` +* `CoreWebView2ControllerOptions` + + + +## See also + + +* [Autofill](../concepts/overview-features-apis.md#autofill) in _Overview of WebView2 APIs_. +* [Printing](../concepts/overview-features-apis.md#printing) in _Overview of WebView2 APIs_. +* [Image capture](../concepts/overview-features-apis.md#image-capture) in _Overview of WebView2 APIs_. +* [Downloads](../concepts/overview-features-apis.md#downloads) in _Overview of WebView2 APIs_. +* [Remote debugging WebView2 WinUI 2 (UWP) apps](../how-to/remote-debugging.md) + +API Reference: +* .NET: [WebView2.DefaultBackgroundColor Property](/dotnet/api/microsoft.web.webview2.winforms.webview2.defaultbackgroundcolor) +* Win32: [ICoreWebView2Controller2::_getDefaultBackgroundColor](/microsoft-edge/webview2/reference/win32/icorewebview2controller2#get_defaultbackgroundcolor) +* Win32: [ICoreWebView2Controller2::_putDefaultBackgroundColor](/microsoft-edge/webview2/reference/win32/icorewebview2controller2#put_defaultbackgroundcolor) + + + +Windows docs: +* [SmartScreen](/windows/security/threat-protection/microsoft-defender-smartscreen/microsoft-defender-smartscreen-overview) +* [WebView2.Source property](/windows/winui/api/microsoft.ui.xaml.controls.webview2.source) +* [WebView2.EnsureCoreWebView2Async method](/windows/winui/api/microsoft.ui.xaml.controls.webview2.ensurecorewebview2async) +* [App capability declarations](/windows/uwp/packaging/app-capability-declarations) + +MDN: +* [Values](https://developer.mozilla.org/docs/Web/CSS/cursor#values) in _cursor_ CSS property at MDN. + +WebView2Feedback repo: +* [CSS - cursor loaded from URL doesn't work](https://github.com/MicrosoftEdge/WebView2Feedback/issues/1925) diff --git a/microsoft-edge/webview2/platforms/winui3-windows-app-sdk.md b/microsoft-edge/webview2/platforms/winui3-windows-app-sdk.md new file mode 100644 index 0000000000..a8fc4a1d5a --- /dev/null +++ b/microsoft-edge/webview2/platforms/winui3-windows-app-sdk.md @@ -0,0 +1,109 @@ +--- +title: WebView2 in WinUI 3 (Windows App SDK) apps +description: How to include a WebView2 control within your WinUI 3 (Windows App SDK) app. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 01/24/2025 +--- +# WebView2 in WinUI 3 (Windows App SDK) apps + +The following considerations apply to WebView2 in WinUI 3 (Windows App SDK) apps. + + + +## WinAppSDK supports custom WebView2 environments + +WinAppSDK supports custom WebView2 environments, starting with WinAppSDK 1.5 ([1.5.0-experimental2](/windows/apps/windows-app-sdk/experimental-channel#version-15-experimental-150-experimental2)). For more information, see [WinUI3 WebView2 with a custom CoreWebView2Environment](https://github.com/microsoft/microsoft-ui-xaml/issues/6150). + +To instantiate a custom WebView2 environment, you could initialize WebView2 with one of the overrides of `WebView2.EnsureCoreWebView2Async` (listed below), and pass in your custom `CoreWebView2Environment` (and, optionally, custom `CoreWebView2ControllerOptions`): + +```csharp +public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment) +public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment, CoreWebView2ControllerOptions controllerOptions) +``` + +Also see the example code in [Disabling SmartScreen navigation](#disabling-smartscreen-navigation), below. + +API Reference: +* [WebView2.EnsureCoreWebView2Async](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2.ensurecorewebview2async) +* [CoreWebView2ControllerOptions](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controlleroptions) +* [CoreWebView2Environment](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment) +* [CoreWebView2EnvironmentOptions](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environmentoptions) + + + +## Disabling SmartScreen navigation + +WebView2 sends URLs that are navigated to in your application to the [SmartScreen](/windows/security/threat-protection/microsoft-defender-smartscreen/microsoft-defender-smartscreen-overview) service, to ensure that your customers stay secure. If you want to disable this navigation, use a custom `CoreWebView2Environment`, as follows: + +```csharp +CoreWebView2EnvironmentOptions environmentOptions = new CoreWebView2EnvironmentOptions(); +environmentOptions.AdditionalBrowserArguments = "--disable-features=msSmartScreenProtection"; + +string browserFolder = null; // Use null to get default browser folder +string userDataFolder = null; // Use null to get default user data folder +CoreWebView2Environment environment = await CoreWebView2Environment.CreateWithOptionsAsync( + browserFolder, userDataFolder, environmentOptions); + +// ... + +this.WebView2.EnsureCoreWebView2Async(environment); +``` + + + +## Disabling SmartScreen by using an environment variable + +We no longer recommend using an environment variable. Use the above API code-based approach instead. + +* `Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");` + +This environment variable must be set prior to `CoreWebView2` creation, which occurs when the [WebView2.Source property](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2.source#microsoft-ui-xaml-controls-webview2-source) is initially set or the [WebView2.EnsureCoreWebView2Async method](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2.ensurecorewebview2async#microsoft-ui-xaml-controls-webview2-ensurecorewebview2async) is initially called. + + + +## Setting DefaultBackgroundColor + +In WebView2 for WinUI 3, the `DefaultBackgroundColor` setting exists on the WebView2 XAML object. For example: + +```csharp +public MainWindow() +{ + this.InitializeComponent(); + MyWebView.DefaultBackgroundColor = Colors.LightBlue; +} +``` + + + +## Transparency + +WinUI 3 doesn't support transparent backgrounds. See [Transparent background support for WebView2? · Issue #2992](https://github.com/microsoft/microsoft-ui-xaml/issues/2992). + + + +## See also + + +microsoft-ui-xaml Repo > Issues +* [WinUI3 WebView2 with a custom CoreWebView2Environment](https://github.com/microsoft/microsoft-ui-xaml/issues/6150). +* [Transparent background support for WebView2? · Issue #2992](https://github.com/microsoft/microsoft-ui-xaml/issues/2992) + +Windows apps docs: +* [1.5.0-experimental2](/windows/apps/windows-app-sdk/experimental-channel#version-15-experimental-150-experimental2) + +Windows App SDK Reference: +* [WebView2.EnsureCoreWebView2Async](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2.ensurecorewebview2async) +* [WebView2.Source property](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2.source#microsoft-ui-xaml-controls-webview2-source) +* [WebView2.EnsureCoreWebView2Async method](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2.ensurecorewebview2async#microsoft-ui-xaml-controls-webview2-ensurecorewebview2async) + +WebView2 Reference: +* [CoreWebView2ControllerOptions](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controlleroptions) +* [CoreWebView2Environment](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment) +* [CoreWebView2EnvironmentOptions](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environmentoptions) + +Windows Security docs: +* [SmartScreen](/windows/security/threat-protection/microsoft-defender-smartscreen/microsoft-defender-smartscreen-overview) diff --git a/microsoft-edge/webview2/platforms/wpf.md b/microsoft-edge/webview2/platforms/wpf.md new file mode 100644 index 0000000000..d1b7f0603a --- /dev/null +++ b/microsoft-edge/webview2/platforms/wpf.md @@ -0,0 +1,54 @@ +--- +title: WebView2 in WPF apps +description: How to include a WebView2 control within your WPF app. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 01/27/2025 +--- +# WebView2 in WPF apps + +The following considerations apply to WebView2 in WPF apps. + + + +## Show WPF elements on top of the WebView2 layer (WebView2CompositionControl) + +The `WebView2CompositionControl` prevents the WebView2 control from being the topmost layer in a WPF app and obscuring any WPF elements. `Microsoft.Web.WebView2.Wpf.WebView2CompositionControl` is a drop-in replacement for the standard WPF WebView2 control. Both the WebView2 control and `WebView2CompositionControl` implement the `Microsoft.Web.WebView2.Wpf.IWebView2` interface. Both of them derive from `FrameworkElement`, as follows: +* `FrameworkElement` -> `HwndHost` -> `WebView2`. +* `FrameworkElement` -> `Control` -> `WebView2CompositionControl`. + +Background: If you're building a Windows Presentation Foundation (WPF) app and using the WebView2 control, you may find that your app runs into "airspace" issues, where the WebView2 control is always displayed on top, hiding any WPF elements in the same location, even if you try to specify the WPF elements to be above the WebView2 control (using visual tree order or the z-index property, for example). + +This issue occurs because the WPF control uses the WPF `HwndHost` to host the Win32 WebView2 control, and `HwndHost` has an issue with airspace. + +See also: +* [Mitigating Airspace Issues In WPF Applications](https://dwayneneed.github.io/wpf/2013/02/26/mitigating-airspace-issues-in-wpf-applications.html) +* [WPF Airspace - WebView2CompositionControl](https://github.com/MicrosoftEdge/WebView2Feedback/blob/main/specs/WPF_WebView2CompositionControl.md) - Spec. + +##### [.NET/C#](#tab/dotnetcsharp) + +* [WebView2CompositionControl Class](/dotnet/api/microsoft.web.webview2.wpf.webview2compositioncontrol) + +##### [WinRT/C#](#tab/winrtcsharp) + +n/a + +##### [Win32/C++](#tab/win32cpp) + +n/a + +--- + + + +## See also + + +* [WebView2CompositionControl Class](/dotnet/api/microsoft.web.webview2.wpf.webview2compositioncontrol) + +Airspace: +* [Mitigating Airspace Issues In WPF Applications](https://dwayneneed.github.io/wpf/2013/02/26/mitigating-airspace-issues-in-wpf-applications.html) +* [WPF Airspace - WebView2CompositionControl](https://github.com/MicrosoftEdge/WebView2Feedback/blob/main/specs/WPF_WebView2CompositionControl.md) - Spec. diff --git a/microsoft-edge/webview2/release-notes/index.md b/microsoft-edge/webview2/release-notes/index.md index a738843ad6..85bed05a10 100644 --- a/microsoft-edge/webview2/release-notes/index.md +++ b/microsoft-edge/webview2/release-notes/index.md @@ -53,10 +53,11 @@ The `WebView2CompositionControl` prevents the WebView2 control from being the to Background: If you're building a Windows Presentation Foundation (WPF) app and using the WebView2 control, you may find that your app runs into "airspace" issues, where the WebView2 control is always displayed on top, hiding any WPF elements in the same location, even if you try to specify the WPF elements to be above the WebView2 control (using visual tree order or the z-index property, for example). -This issue occurs because the WPF control uses the WPF `HwndHost` to host the Win32 WebView2 control, and `HwndHost` has an issue with airspace; see [Mitigating Airspace Issues In WPF Applications](https://dwayneneed.github.io/wpf/2013/02/26/mitigating-airspace-issues-in-wpf-applications.html). +This issue occurs because the WPF control uses the WPF `HwndHost` to host the Win32 WebView2 control, and `HwndHost` has an issue with airspace. See also: -* [PR 4804: WPF Airspace - WebView2CompositionControl](https://github.com/MicrosoftEdge/WebView2Feedback/pull/4804/files?short_path=ebbc3ee#diff-ebbc3ee3560606e2823d68c134ea4aebdc1cb1252aaa9aa2b9a2815e2d8d36b2) - Spec. +* [Mitigating Airspace Issues In WPF Applications](https://dwayneneed.github.io/wpf/2013/02/26/mitigating-airspace-issues-in-wpf-applications.html) +* [WPF Airspace - WebView2CompositionControl](https://github.com/MicrosoftEdge/WebView2Feedback/blob/main/specs/WPF_WebView2CompositionControl.md) - Spec. ##### [.NET/C#](#tab/dotnetcsharp) @@ -291,7 +292,7 @@ The DefaultBackgroundColor API allows users to set the `DefaultBackgroundColor` ##### [WinRT/C#](#tab/winrtcsharp) -* [CoreWebView2ControllerOptions Class](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controlleroptions?view=webview2-winrt-1.0.3079-prerelease&preserve-view=true) +* `CoreWebView2ControllerOptions` Class: * [CoreWebView2ControllerOptions.DefaultBackgroundColor Property](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controlleroptions?view=webview2-winrt-1.0.3079-prerelease&preserve-view=true#defaultbackgroundcolor) ##### [Win32/C++](#tab/win32cpp) @@ -318,10 +319,11 @@ The `WebView2CompositionControl` prevents the WebView2 control from being the to Background: If you're building a Windows Presentation Foundation (WPF) app and using the WebView2 control, you may find that your app runs into "airspace" issues, where the WebView2 control is always displayed on top, hiding any WPF elements in the same location, even if you try to specify the WPF elements to be above the WebView2 control (using visual tree order or the z-index property, for example). -This issue occurs because the WPF control uses the WPF `HwndHost` to host the Win32 WebView2 control, and `HwndHost` has an issue with airspace; see [Mitigating Airspace Issues In WPF Applications](https://dwayneneed.github.io/wpf/2013/02/26/mitigating-airspace-issues-in-wpf-applications.html). +This issue occurs because the WPF control uses the WPF `HwndHost` to host the Win32 WebView2 control, and `HwndHost` has an issue with airspace. See also: -* [PR 4804: WPF Airspace - WebView2CompositionControl](https://github.com/MicrosoftEdge/WebView2Feedback/pull/4804/files?short_path=ebbc3ee#diff-ebbc3ee3560606e2823d68c134ea4aebdc1cb1252aaa9aa2b9a2815e2d8d36b2) - Spec. +* [Mitigating Airspace Issues In WPF Applications](https://dwayneneed.github.io/wpf/2013/02/26/mitigating-airspace-issues-in-wpf-applications.html) +* [WPF Airspace - WebView2CompositionControl](https://github.com/MicrosoftEdge/WebView2Feedback/blob/main/specs/WPF_WebView2CompositionControl.md) - Spec. ##### [.NET/C#](#tab/dotnetcsharp) diff --git a/microsoft-edge/webview2/samples/webview2-winui3-sample.md b/microsoft-edge/webview2/samples/webview2-winui3-sample.md index 7dfff9057c..384042c735 100644 --- a/microsoft-edge/webview2/samples/webview2-winui3-sample.md +++ b/microsoft-edge/webview2/samples/webview2-winui3-sample.md @@ -431,7 +431,7 @@ public MainWindow() } }; - AddressBar.Text = "https://developer.microsoft.com/en-us/microsoft-edge/webview2/"; + AddressBar.Text = "https://developer.microsoft.com/microsoft-edge/webview2/"; WebView2.NavigationCompleted += WebView2_NavigationCompleted; WebView2.CoreWebView2Initialized += WebView2_CoreWebView2Initialized;