[Breaking Change] Granular process failure reasons for the ProcessFailed event

[vootlasaichandu]

[Breaking Change] Granular Process Failure Reasons in WebView2

Summary:

WebView2's ProcessFailed event currently reports Unexpected as the failure reason for three distinct process exit scenarios: normal exit, abnormal exit, and code integrity failure. This change adds three new granular values to CoreWebView2ProcessFailedReason, gated behind a feature flag for backward compatibility.

Details:

• Feature flag name: msWebView2GranularProcessFailedReason
• Scope: ProcessFailed event's Reason property
• Purpose of feature: Allow apps to distinguish between different types of unexpected
  process exits for better diagnostics, telemetry, and error handling.

New Enum Values:

Value	Description
NormalExit	The process exited normally (exit code 0). Typically a clean or transparent process shutdown.
AbnormalExit	The process exited abnormally (non-zero exit code). An unexpected termination that is not a crash or kill.
IntegrityFailure	The OS terminated the process due to a code integrity failure (e.g., a DLL failed Windows Code Integrity verification).

These values were previously all reported as Unexpected.

Impact:

• Expected Behavior Change: When the feature flag is enabled, get_Reason() / CoreWebView2ProcessFailedEventArgs.Reason will return the new granular values instead of Unexpected for the corresponding exit scenarios. When disabled (default), behavior is unchanged — all three continue to return Unexpected.
• Who is Affected: WebView2 apps that handle the ProcessFailed event and check the Reason property. Apps with switch/if statements that don't have a default case for unknown reason values may need updating.

Rollout:

• 148 (Current): Off (flag gated) — msWebView2GranularProcessFailedReason feature flag is disabled by default. Existing behavior preserved. Apps can opt in to test.
• 149: Off (flag gated) — Feature flag remains disabled by default. Second release for apps to proactively test and validate.
• 150: On by default — Feature flag enabled by default. Apps will start receiving granular values (NormalExit, AbnormalExit, IntegrityFailure) instead of Unexpected.
• Future (TBD): Feature flag removal — granular values become the permanent behavior.

Testing:

• How to test prior to release: Set the following environment variable before launching your WebView2 app:

  set WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--enable-features=msWebView2GranularProcessFailedReason
  

  Then trigger process failures and verify your ProcessFailed event handler correctly handles the new Reason values.

Known Issues/Changes:

• The Reason property will return new enum values that did not exist before. Apps that use exhaustive switch statements without a default case may encounter warnings or unexpected behavior.
• This is a runtime-only behavioral change when the flag is enabled. No SDK update is required to maintain existing behavior.

WebView2 Mitigations:

• Feature flag msWebView2GranularProcessFailedReason is disabled by default in releases 148 and 149, preserving existing behavior and giving apps two releases to test.
• When the flag is off, all three exit scenarios continue to report Unexpected exactly as before.

App Actions:

• No immediate action required. The feature is disabled by default in releases 148–149.
• Recommended: Review your ProcessFailed event handlers. Ensure they have a default case or handle unknown Reason values gracefully, so they work correctly when granular values are enabled by default in release 150.
• Proactive testing: Test with the feature flag enabled during releases 148–149 to identify any impact early.

Timeline and Next Steps:

• Feature Enablement: The feature will be enabled by default in release 150. Apps have releases 148 and 149 to proactively test with the feature flag.
• Testing Deadline: Before release 150. Apps are encouraged to test during releases 148–149 to identify any impact.
• Contact: For questions or concerns, please use the https://github.com/MicrosoftEdge/WebView2Feedback.