Skip to content

Commit

Permalink
RestartRequested Update API Review (#4733)
Browse files Browse the repository at this point in the history 
* Update doc and api section

* update sample code

* update sample code

* Fix event handler -> args property

* Update doc to not include event invoke reasons. Update winrt code

* remove blank lone

* add event args runtime class

* fix typo

* fix typo

* Update specs/RestartRequested.md

Co-authored-by: David Risney <[email protected]>

* Update specs/RestartRequested.md

Co-authored-by: David Risney <[email protected]>

* Update specs/RestartRequested.md

Co-authored-by: David Risney <[email protected]>

* Update specs/RestartRequested.md

Co-authored-by: David Risney <[email protected]>

* Change priority level naming. fix longer line

* Typo

* Update specs/RestartRequested.md

Co-authored-by: David Risney <[email protected]>

* remove repeat line

* Update specs/RestartRequested.md

Co-authored-by: Viktoria Zlatinova <[email protected]>

* Update to be more extenable

* Update .net

---------

Co-authored-by: Diana Qu <[email protected]>
Co-authored-by: David Risney <[email protected]>
Co-authored-by: Viktoria Zlatinova <[email protected]>
  • Loading branch information
@dianaqu @david-risney @vickiez
4 people authored Aug 28, 2024
1 parent 594042e commit 06c130e
Showing 1 changed file with 74 additions and 26 deletions.
100 changes: 74 additions & 26 deletions specs/RestartRequested.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
Critical Update Available
Restart Requested
===

# 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.
There are often times when WebView2 needs to be restarted to apply certain updates or change
configuration. The purpose of this API is to detect whether such a restart is requested and
to provide the urgency of the restart. WebView2 developers can listen to this event for version
updates, version downgrades, or important configuration changes to determine if they need to
prompt the user for a restart to apply those updates.

# Examples
## WinRT and .NET
## WinRT and .NET
```c#
void WebView_CoreWebView2InitializationCompleted(object sender, CoreWebView2InitializationCompletedEventArgs e)
{
Expand All @@ -20,11 +20,20 @@ void WebView_CoreWebView2InitializationCompleted(object sender, CoreWebView2Init
}
}

void WebView_RestartRequested(CoreWebView2Environment sender, object e)
void WebView_RestartRequested(CoreWebView2Environment sender, CoreWebView2RestartRequestedEventArgs e)
{
// Depending on your app experience, you may or may not
// want to prompt user to restart the app.
RestartIfSelectedByUser();
if (e.Priority <= CoreWebView2RestartRequestedPriority.Normal)
{
// Depending on your app experience, you should remind the user
// to restart on normal cadence.
RemindToRestartForUpdate();
}
else
{
// Depending on your app experience, you should prompt
// the user to save their current state and restart or otherwise more urgently restart the WebView2.
RestartIfSelectedByUser();
}
}
```

Expand All @@ -36,11 +45,22 @@ void CoreWebView2InitializationCompleted() {
if (env10) {
CHECK_FAILURE(env10->add_RestartRequested(
Callback<ICoreWebView2RestartRequestedEventHandler>(
[this](ICoreWebView2Environment* sender, IUnknown* args) -> HRESULT
[this](ICoreWebView2Environment* sender, ICoreWebView2RestartRequestedEventArgs* args) -> HRESULT
{
// Depending on your app experience, you may or may not
// want to prompt user to restart the app.
RestartIfSelectedByUser();
COREWEBVIEW2_RESTART_REQUESTED_PRIORITY priority;
CHECK_FAILURE(args->get_Priority(&priority));
if (priority <= COREWEBVIEW2_RESTART_REQUESTED_PRIORITY_NORMAL)
{
// Depending on your app experience, you should remind user
// to restart on normal cadence.
RemindToRestartForUpdate();
}
else
{
// Depending on your app experience, you should prompt
// user to save their current state and restart.
RestartIfSelectedByUser();
}
return S_OK;
})
.Get(),
Expand All @@ -59,25 +79,42 @@ See [API Details](#api-details) section below for API reference.
```IDL
interface ICoreWebView2Environment10;
interface ICoreWebView2RestartRequestedEventHandler;
interface ICoreWebView2RestartRequestedEventArgs;
/// Specifies the restart requested priority from
/// `ICoreWebView2RestartRequestedEventArgs` interface.
[v1_enum]
typedef enum COREWEBVIEW2_RESTART_REQUESTED_PRIORITY {
/// Developer should remind user to restart.
COREWEBVIEW2_RESTART_REQUESTED_PRIORITY_NORMAL = 1000,
/// Developer should prompt user to restart as soon as possible.
COREWEBVIEW2_RESTART_REQUESTED_PRIORITY_HIGH = 2000,
} COREWEBVIEW2_RESTART_REQUESTED_PRIORITY;
[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);
/// Provides the event args for the corresponding event.
HRESULT Invoke(
[in] ICoreWebView2Environment* sender,
[in] ICoreWebView2RestartRequestedEventArgs* args);
}
/// Event args for the `RestartRequested` event.
[uuid(6dbfe971-a69e-4338-9b6e-b0ec9f12424f), object, pointer_default(unique)]
interface ICoreWebView2RestartRequestedEventArgs : IUnknown {
/// Get the restart requested priority.
[propget] HRESULT Priority([out, retval] COREWEBVIEW2_RESTART_REQUESTED_PRIORITY* value);
}
[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.
/// `RestartRequested` event is raised when there is a need to restart WebView2 process
/// in order to apply certain beneifical updates.
///
/// `RestartRequested` gives developers the awareness of these necessary WebView2 restarts,
/// allowing developers to resolve issues faster than waiting for end users to restart the app.
/// Developer might want to give end users the ability to save their state before restarting.
/// 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.
Expand All @@ -98,10 +135,21 @@ s
```c#
namespace Microsoft.Web.WebView2.Core
{
enum CoreWebView2RestartRequestedPriority
{
Normal = 1000,
High = 2000,
};

runtimeclass CoreWebView2RestartRequestedEventArgs
{
CoreWebView2RestartRequestedPriority Priority { get; };
}

runtimeclass CoreWebView2Environment
{
// ...
event Windows.Foundation.TypedEventHandler<CoreWebView2Environment, Object> RestartRequested;
event Windows.Foundation.TypedEventHandler<CoreWebView2Environment, CoreWebView2RestartRequestedEventArgs> RestartRequested;
}
}
```

0 comments on commit 06c130e

Please sign in to comment.