Skip to content

Commit 06c130e

Browse files
Diana QuDiana Qudavid-risneyvickiez
authored
RestartRequested Update API Review (#4733)
* 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 <dave@deletethis.net> * Update specs/RestartRequested.md Co-authored-by: David Risney <dave@deletethis.net> * Update specs/RestartRequested.md Co-authored-by: David Risney <dave@deletethis.net> * Update specs/RestartRequested.md Co-authored-by: David Risney <dave@deletethis.net> * Change priority level naming. fix longer line * Typo * Update specs/RestartRequested.md Co-authored-by: David Risney <dave@deletethis.net> * remove repeat line * Update specs/RestartRequested.md Co-authored-by: Viktoria Zlatinova <vizlatin@microsoft.com> * Update to be more extenable * Update .net --------- Co-authored-by: Diana Qu <xiaqu@microsoft.com> Co-authored-by: David Risney <dave@deletethis.net> Co-authored-by: Viktoria Zlatinova <vizlatin@microsoft.com>
1 parent 594042e commit 06c130e

1 file changed

Lines changed: 74 additions & 26 deletions

File tree

‎specs/RestartRequested.md‎

Lines changed: 74 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
1-
Critical Update Available
1+
Restart Requested
22
===
33

44
# Background
5-
As WebView2 developers, we often have to author ECS (experimentation and configuration service -
6-
used to perform A/B testing or remotely disable features) configurations to toggle feature flags.
7-
However, once these payloads are received, there is no way to restart the WebView2 and apply the
8-
payload. The purpose of this API is to detect such critical payloads and inform the end developer
9-
so they may restart their app or their WebView2 or other appropriate action.
5+
There are often times when WebView2 needs to be restarted to apply certain updates or change
6+
configuration. The purpose of this API is to detect whether such a restart is requested and
7+
to provide the urgency of the restart. WebView2 developers can listen to this event for version
8+
updates, version downgrades, or important configuration changes to determine if they need to
9+
prompt the user for a restart to apply those updates.
1010

1111
# Examples
12-
## WinRT and .NET
12+
## WinRT and .NET
1313
```c#
1414
void WebView_CoreWebView2InitializationCompleted(object sender, CoreWebView2InitializationCompletedEventArgs e)
1515
{
@@ -20,11 +20,20 @@ void WebView_CoreWebView2InitializationCompleted(object sender, CoreWebView2Init
2020
}
2121
}
2222

23-
void WebView_RestartRequested(CoreWebView2Environment sender, object e)
23+
void WebView_RestartRequested(CoreWebView2Environment sender, CoreWebView2RestartRequestedEventArgs e)
2424
{
25-
// Depending on your app experience, you may or may not
26-
// want to prompt user to restart the app.
27-
RestartIfSelectedByUser();
25+
if (e.Priority <= CoreWebView2RestartRequestedPriority.Normal)
26+
{
27+
// Depending on your app experience, you should remind the user
28+
// to restart on normal cadence.
29+
RemindToRestartForUpdate();
30+
}
31+
else
32+
{
33+
// Depending on your app experience, you should prompt
34+
// the user to save their current state and restart or otherwise more urgently restart the WebView2.
35+
RestartIfSelectedByUser();
36+
}
2837
}
2938
```
3039

@@ -36,11 +45,22 @@ void CoreWebView2InitializationCompleted() {
3645
if (env10) {
3746
CHECK_FAILURE(env10->add_RestartRequested(
3847
Callback<ICoreWebView2RestartRequestedEventHandler>(
39-
[this](ICoreWebView2Environment* sender, IUnknown* args) -> HRESULT
48+
[this](ICoreWebView2Environment* sender, ICoreWebView2RestartRequestedEventArgs* args) -> HRESULT
4049
{
41-
// Depending on your app experience, you may or may not
42-
// want to prompt user to restart the app.
43-
RestartIfSelectedByUser();
50+
COREWEBVIEW2_RESTART_REQUESTED_PRIORITY priority;
51+
CHECK_FAILURE(args->get_Priority(&priority));
52+
if (priority <= COREWEBVIEW2_RESTART_REQUESTED_PRIORITY_NORMAL)
53+
{
54+
// Depending on your app experience, you should remind user
55+
// to restart on normal cadence.
56+
RemindToRestartForUpdate();
57+
}
58+
else
59+
{
60+
// Depending on your app experience, you should prompt
61+
// user to save their current state and restart.
62+
RestartIfSelectedByUser();
63+
}
4464
return S_OK;
4565
})
4666
.Get(),
@@ -59,25 +79,42 @@ See [API Details](#api-details) section below for API reference.
5979
```IDL
6080
interface ICoreWebView2Environment10;
6181
interface ICoreWebView2RestartRequestedEventHandler;
82+
interface ICoreWebView2RestartRequestedEventArgs;
83+
84+
/// Specifies the restart requested priority from
85+
/// `ICoreWebView2RestartRequestedEventArgs` interface.
86+
[v1_enum]
87+
typedef enum COREWEBVIEW2_RESTART_REQUESTED_PRIORITY {
88+
/// Developer should remind user to restart.
89+
COREWEBVIEW2_RESTART_REQUESTED_PRIORITY_NORMAL = 1000,
90+
/// Developer should prompt user to restart as soon as possible.
91+
COREWEBVIEW2_RESTART_REQUESTED_PRIORITY_HIGH = 2000,
92+
} COREWEBVIEW2_RESTART_REQUESTED_PRIORITY;
6293
6394
[uuid(62cb67c6-b6a9-4209-8a12-72ca093b9547), object, pointer_default(unique)]
6495
interface ICoreWebView2RestartRequestedEventHandler : IUnknown {
65-
/// Provides the event args for the corresponding event. No event args exist
66-
/// and the `args` parameter is set to `null`.
67-
HRESULT Invoke([in] ICoreWebView2Environment* sender, [in] IUnknown* args);
96+
/// Provides the event args for the corresponding event.
97+
HRESULT Invoke(
98+
[in] ICoreWebView2Environment* sender,
99+
[in] ICoreWebView2RestartRequestedEventArgs* args);
100+
}
101+
102+
/// Event args for the `RestartRequested` event.
103+
[uuid(6dbfe971-a69e-4338-9b6e-b0ec9f12424f), object, pointer_default(unique)]
104+
interface ICoreWebView2RestartRequestedEventArgs : IUnknown {
105+
/// Get the restart requested priority.
106+
[propget] HRESULT Priority([out, retval] COREWEBVIEW2_RESTART_REQUESTED_PRIORITY* value);
68107
}
69108
70109
[uuid(ef7632ec-d86e-46dd-9d59-e6ffb5c87878), object, pointer_default(unique)]
71110
interface ICoreWebView2Environment10 : IUnknown {
72111
/// Add an event handler for the `RestartRequested` event.
73-
/// `RestartRequested` event is raised when there is an urgent need to
74-
/// restart the WebView2 process in order to enable or disable
75-
/// features that are causing WebView2 reliability or performance to drop critically.
76-
/// `RestartRequested` gives you the awareness of these necessary WebView2 restarts,
77-
/// allowing you to resolve issues faster than waiting for your end users to restart the app.
78-
/// Depending on your app you may want to prompt your end users in some way to give
79-
/// them a chance to save their state before you restart the WebView2.
112+
/// `RestartRequested` event is raised when there is a need to restart WebView2 process
113+
/// in order to apply certain beneifical updates.
80114
///
115+
/// `RestartRequested` gives developers the awareness of these necessary WebView2 restarts,
116+
/// allowing developers to resolve issues faster than waiting for end users to restart the app.
117+
/// Developer might want to give end users the ability to save their state before restarting.
81118
/// For apps with multiple processes that host WebView2s that share the same user data folder you
82119
/// need to make sure all WebView2 instances are closed and the associated WebView2 Runtime
83120
/// browser process exits. See `BrowserProcessExited` for more details.
@@ -98,10 +135,21 @@ s
98135
```c#
99136
namespace Microsoft.Web.WebView2.Core
100137
{
138+
enum CoreWebView2RestartRequestedPriority
139+
{
140+
Normal = 1000,
141+
High = 2000,
142+
};
143+
144+
runtimeclass CoreWebView2RestartRequestedEventArgs
145+
{
146+
CoreWebView2RestartRequestedPriority Priority { get; };
147+
}
148+
101149
runtimeclass CoreWebView2Environment
102150
{
103151
// ...
104-
event Windows.Foundation.TypedEventHandler<CoreWebView2Environment, Object> RestartRequested;
152+
event Windows.Foundation.TypedEventHandler<CoreWebView2Environment, CoreWebView2RestartRequestedEventArgs> RestartRequested;
105153
}
106154
}
107155
```

0 commit comments

Comments
 (0)