From c1384219624ecd54921ae93501ba08c0e9407331 Mon Sep 17 00:00:00 2001 From: Diana Qu Date: Thu, 11 Jul 2024 13:57:36 -0700 Subject: [PATCH] Add Spec: Critical Restart Required (#4657) * Add Spec: Critical Kill Switch (#4574) * add critical api --------- Co-authored-by: Diana Qu Co-authored-by: David Risney * Sample code update Co-authored-by: MikeHillberg <18429489+MikeHillberg@users.noreply.github.com> * Fix typo Co-authored-by: Viktoria Zlatinova * renaming API and update doc * renaming md file --------- Co-authored-by: Diana Qu Co-authored-by: David Risney Co-authored-by: MikeHillberg <18429489+MikeHillberg@users.noreply.github.com> Co-authored-by: Viktoria Zlatinova --- specs/RestartRequested.md | 107 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 specs/RestartRequested.md diff --git a/specs/RestartRequested.md b/specs/RestartRequested.md new file mode 100644 index 00000000..05318f69 --- /dev/null +++ b/specs/RestartRequested.md @@ -0,0 +1,107 @@ +Critical Update Available +=== + +# Background +As WebView2 developers, we often have to author ECS (experimentation and configuration service - +used to perform A/B testing or remotely disable features) configurations to toggle feature flags. +However, once these payloads are received, there is no way to restart the WebView2 and apply the +payload. The purpose of this API is to detect such critical payloads and inform the end developer +so they may restart their app or their WebView2 or other appropriate action. + +# Examples +## WinRT and .NET +```c# +void WebView_CoreWebView2InitializationCompleted(object sender, CoreWebView2InitializationCompletedEventArgs e) +{ + if (e.IsSuccess) + { + // ... + webView.CoreWebView2.Environment.RestartRequested += WebView_RestartRequested; + } +} + +void WebView_RestartRequested(CoreWebView2Environment sender, object e) +{ + // Depending on your app experience, you may or may not + // want to prompt user to restart the app. + RestartIfSelectedByUser(); +} +``` + +## Win32 C++ +```cpp +wil::com_ptr m_webViewEnvironment; +void CoreWebView2InitializationCompleted() { + auto env10 = m_webViewEnvironment.try_query(); + if (env10) { + CHECK_FAILURE(env10->add_RestartRequested( + Callback( + [this](ICoreWebView2Environment* sender, IUnknown* args) -> HRESULT + { + // Depending on your app experience, you may or may not + // want to prompt user to restart the app. + RestartIfSelectedByUser(); + return S_OK; + }) + .Get(), + nullptr)); + } +} +``` + +# API Notes + +See [API Details](#api-details) section below for API reference. + +# API Details +## Win32 C++ + +```IDL +interface ICoreWebView2Environment10; +interface ICoreWebView2RestartRequestedEventHandler; + +[uuid(62cb67c6-b6a9-4209-8a12-72ca093b9547), object, pointer_default(unique)] +interface ICoreWebView2RestartRequestedEventHandler : IUnknown { + /// Provides the event args for the corresponding event. No event args exist + /// and the `args` parameter is set to `null`. + HRESULT Invoke([in] ICoreWebView2Environment* sender, [in] IUnknown* args); +} + +[uuid(ef7632ec-d86e-46dd-9d59-e6ffb5c87878), object, pointer_default(unique)] +interface ICoreWebView2Environment10 : IUnknown { + /// Add an event handler for the `RestartRequested` event. + /// `RestartRequested` event is raised when there is an urgent need to + /// restart the WebView2 process in order to enable or disable + /// features that are causing WebView2 reliability or performance to drop critically. + /// `RestartRequested` gives you the awareness of these necessary WebView2 restarts, + /// allowing you to resolve issues faster than waiting for your end users to restart the app. + /// Depending on your app you may want to prompt your end users in some way to give + /// them a chance to save their state before you restart the WebView2. + /// + /// For apps with multiple processes that host WebView2s that share the same user data folder you + /// need to make sure all WebView2 instances are closed and the associated WebView2 Runtime + /// browser process exits. See `BrowserProcessExited` for more details. + // MSOWNERS: xiaqu@microsoft.com + HRESULT add_RestartRequested( + [in] ICoreWebView2RestartRequestedEventHandler* eventHandler, + [out] EventRegistrationToken* token); + + /// Remove an event handler previously added with `add_RestartRequested`. + // MSOWNERS: xiaqu@microsoft.com + HRESULT remove_RestartRequested( + [in] EventRegistrationToken token); +} +``` +s +## .NET and WinRT + +```c# +namespace Microsoft.Web.WebView2.Core +{ + runtimeclass CoreWebView2Environment + { + // ... + event Windows.Foundation.TypedEventHandler RestartRequested; + } +} +``` \ No newline at end of file