[Windows] Fix WebView blank rendering when used with HybridWebView

[SubhikshaSf4851]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment whether this change resolves your issue. Thank you!

This pull request addresses an issue where the WebView rendered blank when both a HybridWebView and a regular WebView coexisted in the same Windows (UWP) app. The main fix ensures that HybridWebView only creates a custom CoreWebView2Environment if custom settings are provided, allowing both controls to share the default environment and preventing conflicts. Additionally, new test cases have been added to verify the fix.

Description of Change

Bug fix for WebView and HybridWebView coexistence:

• Updated HybridWebViewHandler.Windows.cs so that a custom CoreWebView2Environment is created only if the user provides custom settings; otherwise, the default shared environment is used. This prevents conflicts when both HybridWebView and WebView are present in the same app, resolving the blank rendering issue. [1] [2]

Test coverage improvements:

• Added a new UI test in TestCases.Shared.Tests/Tests/Issues/Issue34558.cs to verify that the regular WebView renders content successfully when coexisting with a HybridWebView.
• Introduced a new test case page in TestCases.HostApp/Issues/Issue34558.cs that sets up both controls and provides UI elements for automated verification.

Issues Fixed

Fixes #34558

Tested the behavior in the following platforms

• Windows
• Android
• iOS
• Mac

Before Issue Fix	After Issue Fix
BeforeFix34558.mp4	AfterFix34558.mp4

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 35092

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 35092"

[dotnet-policy-service]

Hey there @@SubhikshaSf4851! Thank you so much for your PR! Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

[kubaflo]

Hi! Is this one ready for review?

[MauiBot]

🤖 AI Summary

👋 @SubhikshaSf4851 — new AI review results are available. Please review the latest session below.

📊 Review Session — 1a243c7 · Merge branch 'Fix-34558' of https://github.com/SubhikshaSf4851/maui into Fix-34558 · 2026-04-26 01:36 UTC

---

🚦 Gate — Test Before & After Fix

---

Test Verification Report

Date: 2026-04-26 00:20:08 | Platform: WINDOWS | Status: ✅ PASSED

Summary

Check	Expected	Actual	Result
Tests WITHOUT fix	FAIL	FAIL	✅
Tests WITH fix	PASS	PASS	✅

✅ Final Verdict

VERIFICATION PASSED ✅

The tests correctly detect the issue:

• ✅ Tests FAIL without the fix (as expected - bug is present)
• ✅ Tests PASS with the fix (as expected - bug is fixed)

Conclusion: The tests properly validate the fix and catch the bug when it's present.

---

Configuration

Platform: windows
Test Filter: Issue34558
Base Branch: main
Merge Base: d5e39b0

Fix Files

• src/Core/src/Handlers/HybridWebView/HybridWebViewHandler.Windows.cs

---

Test Results Details

Test Run 1: WITHOUT Fix

Expected: Tests should FAIL (bug is present)
Actual: Tests FAILED ✅

View full test output (without fix)

  Determining projects to restore...
  Restored D:\a\1\s\src\Controls\src\Core\Controls.Core.csproj (in 45.01 sec).
  Restored D:\a\1\s\src\Controls\Foldable\src\Controls.Foldable.csproj (in 1.15 sec).
  Restored D:\a\1\s\src\Controls\Maps\src\Controls.Maps.csproj (in 46.1 sec).
  Restored D:\a\1\s\src\BlazorWebView\src\Maui\Microsoft.AspNetCore.Components.WebView.Maui.csproj (in 3.88 sec).
  Restored D:\a\1\s\src\Graphics\src\Graphics.Win2D\Graphics.Win2D.csproj (in 32 ms).
  Restored D:\a\1\s\src\Essentials\src\Essentials.csproj (in 28 ms).
  Restored D:\a\1\s\src\Graphics\src\Graphics\Graphics.csproj (in 4.02 sec).
  Restored D:\a\1\s\src\Core\maps\src\Maps.csproj (in 20 ms).
  Restored D:\a\1\s\src\Core\src\Core.csproj (in 76 ms).
  Restored D:\a\1\s\src\Controls\src\Xaml\Controls.Xaml.csproj (in 24 ms).
  Restored D:\a\1\s\src\Controls\tests\TestCases.HostApp\Controls.TestCases.HostApp.csproj (in 563 ms).
  3 of 14 projects are up-to-date for restore.
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Graphics -> D:\a\1\s\artifacts\bin\Graphics\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Graphics.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Graphics.Win2D -> D:\a\1\s\artifacts\bin\Graphics.Win2D\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Graphics.Win2D.WinUI.Desktop.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Essentials -> D:\a\1\s\artifacts\bin\Essentials\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Essentials.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Core -> D:\a\1\s\artifacts\bin\Core\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.dll
  Controls.BindingSourceGen -> D:\a\1\s\artifacts\bin\Controls.BindingSourceGen\Debug\netstandard2.0\Microsoft.Maui.Controls.BindingSourceGen.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Maps -> D:\a\1\s\artifacts\bin\Maps\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Maps.dll
  Controls.Core -> D:\a\1\s\artifacts\bin\Controls.Core\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Controls.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Controls.Xaml -> D:\a\1\s\artifacts\bin\Controls.Xaml\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Controls.Xaml.dll
  Controls.Foldable -> D:\a\1\s\artifacts\bin\Controls.Foldable\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Controls.Foldable.dll
  Microsoft.AspNetCore.Components.WebView.Maui -> D:\a\1\s\artifacts\bin\Microsoft.AspNetCore.Components.WebView.Maui\Debug\net10.0-windows10.0.19041.0\Microsoft.AspNetCore.Components.WebView.Maui.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Controls.Maps -> D:\a\1\s\artifacts\bin\Controls.Maps\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Controls.Maps.dll
  Controls.TestCases.HostApp -> D:\a\1\s\artifacts\bin\Controls.TestCases.HostApp\Debug\net10.0-windows10.0.19041.0\win-x64\Controls.TestCases.HostApp.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:06:08.35

---

Test Run 2: WITH Fix

Expected: Tests should PASS (bug is fixed)
Actual: Tests PASSED ✅

View full test output (with fix)

  Determining projects to restore...
  All projects are up-to-date for restore.
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Graphics -> D:\a\1\s\artifacts\bin\Graphics\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Graphics.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Graphics.Win2D -> D:\a\1\s\artifacts\bin\Graphics.Win2D\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Graphics.Win2D.WinUI.Desktop.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Essentials -> D:\a\1\s\artifacts\bin\Essentials\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Essentials.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Core -> D:\a\1\s\artifacts\bin\Core\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.dll
  Controls.BindingSourceGen -> D:\a\1\s\artifacts\bin\Controls.BindingSourceGen\Debug\netstandard2.0\Microsoft.Maui.Controls.BindingSourceGen.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Controls.Core -> D:\a\1\s\artifacts\bin\Controls.Core\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Controls.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Controls.Foldable -> D:\a\1\s\artifacts\bin\Controls.Foldable\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Controls.Foldable.dll
  Maps -> D:\a\1\s\artifacts\bin\Maps\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Maps.dll
  ##vso[build.updatebuildnumber]10.0.70-ci+azdo.13938662
  Controls.Xaml -> D:\a\1\s\artifacts\bin\Controls.Xaml\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Controls.Xaml.dll
  Microsoft.AspNetCore.Components.WebView.Maui -> D:\a\1\s\artifacts\bin\Microsoft.AspNetCore.Components.WebView.Maui\Debug\net10.0-windows10.0.19041.0\Microsoft.AspNetCore.Components.WebView.Maui.dll
  Controls.Maps -> D:\a\1\s\artifacts\bin\Controls.Maps\Debug\net10.0-windows10.0.19041.0\Microsoft.Maui.Controls.Maps.dll
  Controls.TestCases.HostApp -> D:\a\1\s\artifacts\bin\Controls.TestCases.HostApp\Debug\net10.0-windows10.0.19041.0\win-x64\Controls.TestCases.HostApp.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:06:02.00

---

Logs

• Full verification log: D:\a\1\s\CustomAgentLogsTmp\PRState\35092\PRAgent\gate\verify-tests-fail\verification-log.txt
• Test output without fix: D:\a\1\s\CustomAgentLogsTmp\PRState\35092\PRAgent\gate\verify-tests-fail\test-without-fix.log
• Test output with fix: D:\a\1\s\CustomAgentLogsTmp\PRState\35092\PRAgent\gate\verify-tests-fail\test-with-fix.log
• UI test logs: CustomAgentLogsTmp/UITests/

---

🧪 UI Tests — Category Detection

---

Detected UI test categories: ViewBaseTests,WebView

---

🔍 Pre-Flight — Context & Validation

---

Issue: #34558 - [Windows] WebView Regression from NET9 to NET10
PR: #35092 - [Windows] Fix WebView blank rendering when used with HybridWebView
Platforms Affected: Windows (UWP)
Files Changed: 1 implementation, 2 test

Key Findings

• Root cause: HybridWebViewHandler.TryInitializeWebView2() always called CoreWebView2Environment.CreateWithOptionsAsync(null, null, null), creating a separate environment object even when no customization was requested. WebView2 requires all controls sharing the same user data folder to use compatible environments, so the custom environment conflicted with the default environment used by regular WebView.
• Fix: Guard behind hasCustomSettings check — only create a CoreWebView2Environment when the user has set at least one custom option; otherwise call EnsureCoreWebView2Async() (no args) to join the shared default environment.
• Test verifies the fix by waiting for WebViewNavigatedLabel which only appears after WebView successfully navigates.
• The hybridroot folder exists at Resources/Raw/hybridroot but has no index.html — HybridWebView will 404 its default page during the test (non-blocking for test validity).

Code Review Summary

Verdict: LGTM
Confidence: high
Errors: 0 | Warnings: 2 | Suggestions: 1

Key code review findings:

• ⚠️ hybridroot test asset lacks index.html; HybridWebView will 404 during test, but test is still valid for its purpose (TestCases.HostApp/Issues/Issue34558.cs)
• ⚠️ hasCustomSettings cannot distinguish "user explicitly set IsInPrivateModeEnabled = false" from "default false" — semantically correct but a comment would clarify intent (HybridWebViewHandler.Windows.cs:320)
• 💡 Test doesn't check that HybridWebView itself rendered successfully (no WaitForElement("HybridWebViewControl") height check)

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #35092	Guard CoreWebView2Environment.CreateWithOptionsAsync behind hasCustomSettings check; use EnsureCoreWebView2Async() for default case	✅ PASSED (Gate)	HybridWebViewHandler.Windows.cs	Original PR

---

🔬 Code Review — Deep Analysis

---

Code Review — PR #35092

Independent Assessment

What this changes: HybridWebViewHandler.Windows.cs — TryInitializeWebView2() previously always called CoreWebView2Environment.CreateWithOptionsAsync(null, null, null), creating a new environment object regardless of whether any customisation was requested. This PR adds a hasCustomSettings guard: if all WebViewInitializationStartedEventArgs fields are at their defaults, it falls back to webView.EnsureCoreWebView2Async() (no args), joining the app's default shared environment. The PR also adds a TestCases host page and UI test for the scenario.

Inferred motivation: On Windows, the WebView2 API requires all controls sharing the same user data folder to use compatible environments. Creating a new environment object (even with all-null params) produces an incompatible instance relative to the default shared environment used by regular WebView controls, causing blank rendering.

---

Reconciliation with PR Narrative

Author claims: Fix blank WebView rendering caused by HybridWebView and WebView coexisting in the same Windows app. Root cause: HybridWebView always created a separate CoreWebView2Environment that conflicted with the default environment used by regular WebView.

Agreement: Full agreement. The code confirms the root cause and the fix is minimal and targeted.

---

Findings

⚠️ Warning — hybridroot test asset lacks index.html; HybridWebView will 404 during the test

src/Controls/tests/TestCases.HostApp/Issues/Issue34558.cs sets HybridRoot = "hybridroot". The Resources\Raw\hybridroot\ folder contains only assets/ and issues/issue-30846.html — there is no index.html. HybridWebView's default file (DefaultFile) is index.html, so the HybridWebView will return a 404 for its initial page load.

The test is still valid for its stated goal (regular WebView navigates successfully when HybridWebView is present), because the 404 doesn't prevent EnsureCoreWebView2Async() from completing — the environment conflict still occurs without the fix and disappears with it. However, the test does not validate that HybridWebView itself is functional, so a future regression that breaks HybridWebView content loading would not be caught by this test.

Consider either: (a) adding a minimal index.html to hybridroot/ and asserting the HybridWebView loaded content, or (b) explicitly noting in the test that HybridWebView content loading is not being verified.

⚠️ Warning — hasCustomSettings does not distinguish "user set it to false" from "default false" for IsInPrivateModeEnabled

// HybridWebViewHandler.Windows.cs:320
initializingArgs.IsInPrivateModeEnabled

IsInPrivateModeEnabled is a bool with a default of false. A user who explicitly sets IsInPrivateModeEnabled = false gets the same result as one who sets nothing — the default environment is used. In practice this is semantically correct (explicitly requesting the default is indistinguishable from not requesting anything), but it means a user who sets only IsInPrivateModeEnabled = false and no other properties will not get an isolated environment. This is the right behavior, but worth a comment to make the intent clear, especially since it's easy to misread the check as "this flag enables custom env."

This is minor; no behavioral bug. But a comment like // bool default = false, so false means "use default" above that line would prevent future confusion.

💡 Suggestion — Test doesn't verify HybridWebView initialized without error

App.WaitForElement("HybridWebViewControl") is never called. Given the fix is specifically about HybridWebView's initialization conflicting with WebView, adding a check that the HybridWebView element is at least present and has a non-zero rect would make the test more complete:

var hybridRect = App.WaitForElement("HybridWebViewControl").GetRect();
Assert.That(hybridRect.Height, Is.GreaterThan(0), "HybridWebView should render with non-zero height");

---

Devil's Advocate

"Is the hasCustomSettings check complete?" — Verified against WebViewInitializationStartedEventArgs.cs: the check covers all six Windows-platform settable properties (BrowserExecutableFolder, UserDataFolder, EnvironmentOptions, ScriptLocale, IsInPrivateModeEnabled, ProfileName). Nothing is missing.

"Could the custom-settings path break?" — The custom path is unchanged from before the PR. Existing behavior for users who have configured custom environments is preserved exactly.

"Does EnsureCoreWebView2Async() (no args) guarantee the same environment as a regular WebView?" — Yes. The no-arg overload instructs WebView2 to use the process-wide default environment, which is exactly what WebView uses natively. This is the documented pattern for sharing an environment between multiple controls.

"Could ScriptLocale = null or ProfileName = null throw in the custom path?" — Those assignments (options.ScriptLocale = null) are pre-existing, not introduced by this PR. Not flagging pre-existing code.

"CI is fully green?" — Gate passed (tests FAIL without fix, PASS with fix). ✅

---

Verdict: LGTM

Confidence: high

Summary: The root cause diagnosis is correct and the fix is minimal and well-targeted. Calling EnsureCoreWebView2Async() without arguments is the right WebView2 API for joining the shared default environment. The two warnings are about test quality (missing index.html in hybridroot/ and no verification of HybridWebView init success), not correctness of the fix. The fix is safe to merge.

---

🔧 Fix — Analysis & Comparison

---

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
1	try-fix (claude-opus-4.6)	Change-tracking setters (HasCustomSettings backing field) in WebViewInitializationStartedEventArgs	✅ PASS	2 files	More extensible but adds state to event args class
2	try-fix (claude-sonnet-4.6)	Public computed property HasCustomEnvironmentSettings in WebViewInitializationStartedEventArgs	✅ PASS	2+ files (requires PublicAPI.Unshipped.txt)	Adds public API surface — unnecessary for a bug fix
3	try-fix (gpt-5.3-codex)	Reflection-based comparison against a default instance in handler	✅ PASS	1 file	Uses reflection — overhead + fragile with new properties
4	try-fix (gpt-5.4)	Split env/controller init paths; EnsureCoreWebView2Async() for default, custom env only when needed	✅ PASS	1 file	Similar structure to PR fix
5	try-fix (gpt-5.3-codex cross-poll)	Explicit UseCustomWebView2Environment opt-in flag on the handler	✅ PASS	Multiple files	Larger API surface change — heavyweight for a bug fix
PR	PR #35092	Inline hasCustomSettings bool guard in TryInitializeWebView2() checking 6 individual properties explicitly	✅ PASSED (Gate)	1 file (HybridWebViewHandler.Windows.cs)	Minimal, single file, no new public API

Cross-Pollination

Model	Round	New Ideas?	Details
claude-opus-4.6	2	No	Design space exhausted — detection vs avoidance variants fully covered
gpt-5.3-codex	2	Yes	Explicit UseCustomWebView2Environment opt-in flag on HybridWebView — tested as attempt 5
gpt-5.4	2	No	No new ideas beyond the 5 attempts

Exhausted: Yes
Selected Fix: PR's fix — Inline hasCustomSettings bool guard in TryInitializeWebView2(). Reason: single-file change, no new public API surface, minimal code, intent is explicit and readable. Alternatives 1-5 either introduce new public API, use reflection overhead, or require multi-file changes without meaningful benefit over the PR's approach.

---

📋 Report — Final Recommendation

---

✅ Final Recommendation: APPROVE

Phase Status

Phase	Status	Notes
Pre-Flight	✅ COMPLETE	Issue #34558 / PR #35092, 1 fix file + 2 test files, Windows only
Code Review	LGTM (high)	0 errors, 2 warnings, 1 suggestion
Gate	✅ PASSED	windows — tests FAIL without fix, PASS with fix
Try-Fix	✅ COMPLETE	5 attempts, 5 passing
Report	✅ COMPLETE

Code Review Impact on Try-Fix

Code review returned LGTM with no ❌ errors, so hints were advisory only. No model had correctness concerns to address — all models focused on exploring architectural alternatives to the PR's inline check. The two warnings (missing hybridroot/index.html and IsInPrivateModeEnabled bool ambiguity) are test quality issues and did not influence fix approaches. The LGTM verdict meant all 5 models freely explored different strategies without being anchored to correcting an error.

Summary

All 5 independent models found working alternatives (change-tracking setters, computed property, reflection, split paths, explicit flag), but the PR's inline hasCustomSettings guard is the simplest and most appropriate solution. It makes a minimal single-file change with no new public API surface and explicitly documents what constitutes "custom settings."

Root Cause

HybridWebViewHandler.TryInitializeWebView2() unconditionally called CoreWebView2Environment.CreateWithOptionsAsync(null, null, null), creating an isolated environment even when no customization was requested. WebView2 requires all controls sharing the same user data folder to use compatible environments — the unconditionally-created environment conflicted with the default shared environment used by regular WebView, causing it to render blank.

Fix Quality

The PR's fix is minimal, correct, and well-targeted. The hasCustomSettings check covers all 6 settable properties of WebViewInitializationStartedEventArgs. The fallback to EnsureCoreWebView2Async() (no args) correctly joins the process-wide default environment. The custom settings path (existing behavior) is fully preserved. Two minor test quality warnings from code review (missing index.html for HybridWebView in the test, no HybridWebView height assertion) are non-blocking and do not affect correctness. Gate verified the fix works.

Selected Fix: PR's fix

---

[Copilot]

Pull request overview

Fixes a Windows WebView2 initialization conflict where HybridWebView could force creation of a separate default CoreWebView2Environment, causing a regular WebView to render blank when both are present in the same app. Adds a new Issue test page and UITest to validate the scenario.

Changes:

• Update HybridWebViewHandler.Windows to only create a custom CoreWebView2Environment when custom initialization settings are provided; otherwise use the default shared environment.
• Add a new HostApp Issue page (Issue34558) that places a HybridWebView and a regular WebView together for automated validation.
• Add a new UI test (Issue34558) that navigates to the Issue page and waits for a post-navigation signal.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
src/Core/src/Handlers/HybridWebView/HybridWebViewHandler.Windows.cs	Avoids creating a separate default WebView2 environment unless customization is requested, reducing conflicts with other WebView2 controls.
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue34558.cs	Adds a UITest that validates the regular WebView successfully navigates when HybridWebView is also present.
src/Controls/tests/TestCases.HostApp/Issues/Issue34558.cs	Adds a HostApp page to reproduce/validate the HybridWebView + WebView coexistence scenario.