Skip to content

Commit f37d0bd

Browse files
LiangTheDevLiangTheDev
authored
Create TryUpdateRuntime
1 parent ab3acaa commit f37d0bd

1 file changed

Lines changed: 225 additions & 0 deletions

File tree

‎specs/TryUpdateRuntime‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Background
2+
The new version of an app might requires a newer version of Edge WebView2 Runtime. The app updater might want to ensure that the newer version of Edge WebView2 Runtime
3+
is installed before updating the app to the newer version. The app could also update to newer version with some feature disabled, and then request update so that it
4+
could move to newer version of Edge WebView2 Runtime and enable those features faster.
5+
Edge WebView2 Runtime is auto updated and normally the latest version should be already installed. However, there could be cases that we need trigger Edge WebView2 Runtime
6+
update to ensure coordinated app and runtime update.
7+
8+
# Description
9+
You may call the `TryUpdateRuntime` API to check and install updates to installed Edge WebView2 Runtime. This is useful when the app wants to coordinate app and
10+
Edge WebView2 Runtime update.
11+
12+
# Examples
13+
## .NET, WinRT
14+
```c#
15+
using Microsoft.Web.WebView2.Core;
16+
async protected bool EnsureWebView2RuntimeVersion(string minimalVersionRequired)
17+
{
18+
string currentRuntimeVersion = CoreWebView2Environment.GetAvailableBrowserVersionString();
19+
if (CoreWebView2Environment.CompareBrowserVersions(currentRuntimeVersion, minimalVersionRequired) < 0)
20+
{
21+
auto environment = await CoreWebView2Environment.CreateAsync();
22+
auto updateResult = await environment.TryUpdateRuntimeAsync();
23+
if (updateResult.UpdateRuntimeStatus != CoreWebView2RuntimeUpdateStatus.Updated)
24+
return false;
25+
}
26+
// check runtime version again
27+
currentRuntimeVersion = CoreWebView2Environment.GetAvailableBrowserVersionString();
28+
return (CoreWebView2Environment.CompareBrowserVersions(currentRuntimeVersion, minimalVersionRequired) >= 0);
29+
}
30+
```
31+
## Win32 C++
32+
```cpp
33+
bool IsCurrentVersionSameOrNewer(std::wstring minimalVersionRequired)
34+
{
35+
wil::unique_cotaskmem_string currentVersion;
36+
HRESULT hr = GetAvailableCoreWebView2BrowserVersionString(nullptr, &currentVersion);
37+
if (FAILED(hr) || (currentVersion == nullptr))
38+
{
39+
return false;
40+
}
41+
int versionComparisonResult;
42+
CompareBrowserVersions(currentVersion.get(), minimalVersionRequired.c_str(), &versionComparisonResult);
43+
return (versionComparisonResult >= 0)
44+
}
45+
46+
void EnsureWebView2RuntimeVersion(std::function<void(bool)> const& callback, std::wstring minimalVersionRequired)
47+
{
48+
if (IsCurrentVersionSameOrNewer(minimalVersionRequired))
49+
{
50+
callback(true);
51+
return;
52+
}
53+
auto options = Microsoft::WRL::Make<CoreWebView2EnvironmentOptions>();
54+
CreateCoreWebView2EnvironmentWithOptions(nullptr, nullptr, options.Get(),
55+
Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
56+
[callback, minimalVersionRequired](HRESULT result, ICoreWebView2Environment* environment) -> HRESULT {
57+
wil::com_ptr<ICoreWebView2Environment> webViewEnvironment = environment;
58+
auto experimentalEnvironment3 =
59+
webViewEnvironment.try_query<ICoreWebView2ExperimentalEnvironment3>();
60+
HRESULT hr = experimentalEnvironment3->TryUpdateRuntime(
61+
Callback<ICoreWebView2ExperimentalTryUpdateRuntimeCompletedHandler>(
62+
[callback, minimalVersionRequired, experimentalEnvironment3](HRESULT errorCode,
63+
ICoreWebView2ExperimentalUpdateRuntimeResult* result) -> HRESULT {
64+
COREWEBVIEW2_RUNTIME_UPDATE_STATUS updateStatus =
65+
COREWEBVIEW2_RUNTIME_UPDATE_STATUS_FAILED;
66+
if ((errorCode == S_OK) && result)
67+
{
68+
CHECK_FAILURE(result->get_UpdateRuntimeStatus(&updateStatus));
69+
}
70+
if (updateStatus != COREWEBVIEW2_RUNTIME_UPDATE_STATUS_UPDATED)
71+
{
72+
callback(false);
73+
}
74+
else
75+
{
76+
callback(IsCurrentVersionSameOrNewer(minimalVersionRequired));
77+
}
78+
return S_OK;
79+
})
80+
.Get());
81+
return S_OK;
82+
})
83+
.Get());
84+
}
85+
86+
```
87+
88+
# Remarks
89+
Try to update installed Microsoft Edge WebView2 Runtime.
90+
This will potentially result in a new version of the Edge Webview2
91+
Runtime being installed and `NewBrowserVersionAvailable` event fired.
92+
There is no guarantee on the order of that event being fired and
93+
TryUpdateRuntimeis completed handler being invoked. Besides the
94+
`NewBrowserVersionAvailable` event, there will be no impact to any
95+
currently running WebViews when update is installed.
96+
The latest version can always be queried using `GetAvailableCoreWebView2BrowserVersionString` API.
97+
This is only supported for installed Edge WebView2 Runtime. When running
98+
fixed version Edge WebView2 Runtime or non stable channel Edge browser,
99+
this API will return `HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)`.
100+
There could only be one active TryUpdateRuntime operation, calling the API
101+
before completed handler for previous call is invoked will fail with
102+
`HRESULT_FROM_WIN32(ERROR_BUSY)`.
103+
Calling the API repeatedly in a short period of time, will also fail with
104+
`HRESULT_FROM_WIN32(ERROR_BUSY)`.
105+
The TryUpdateRuntime operation is associated with the CoreWebView2Environment
106+
object, on going TryUpdateRuntime operation will be aborted when the
107+
associated CoreWebView2Environment along with the CoreWebView2 objects that
108+
are created by the CoreWebView2Environment object are all released.
109+
110+
# API Notes
111+
See [API Details](#api-details) section below for API reference.
112+
113+
# API Details
114+
115+
## Win32 C++
116+
```IDL
117+
/// Result of TryUpdateRuntime operation.
118+
[v1_enum] typedef enum COREWEBVIEW2_RUNTIME_UPDATE_STATUS {
119+
120+
/// No update for Edge WebView2 Runtime is available.
121+
COREWEBVIEW2_RUNTIME_UPDATE_STATUS_NO_UPDATE,
122+
123+
/// Edge WebView2 Runtime is updated successfully.
124+
COREWEBVIEW2_RUNTIME_UPDATE_STATUS_UPDATED,
125+
126+
/// Edge WebView2 Runtime update is blocked by group policy. The caller
127+
/// should not retry.
128+
COREWEBVIEW2_RUNTIME_UPDATE_STATUS_BLOCKED_BY_POLICY,
129+
130+
/// Edge WebView2 Runtime update failed.
131+
COREWEBVIEW2_RUNTIME_UPDATE_STATUS_FAILED,
132+
} COREWEBVIEW2_RUNTIME_UPDATE_STATUS;
133+
134+
/// The TryUpdateRuntime result.
135+
[uuid(DD503E49-AB19-47C0-B2AD-6DDD09CC3E3A), object, pointer_default(unique)]
136+
interface ICoreWebView2ExperimentalUpdateRuntimeResult : IUnknown {
137+
138+
/// The status for the TryUpdateRuntime method.
139+
[propget] HRESULT UpdateRuntimeStatus(
140+
[ out, retval ] COREWEBVIEW2_RUNTIME_UPDATE_STATUS * updateResult);
141+
142+
/// The update error happened while trying to update Edge WebView2 Runtime.
143+
[propget] HRESULT UpdateError([out, retval] HRESULT* updateError);
144+
}
145+
146+
/// The caller implements this interface to receive the TryUpdateRuntime result.
147+
[uuid(F1D2D722-3721-499C-87F5-4C405260697A), object, pointer_default(unique)]
148+
interface ICoreWebView2ExperimentalTryUpdateRuntimeCompletedHandler : IUnknown {
149+
150+
/// Provides the result for the TryUpdateRuntime method.
151+
/// `errorCode` will be S_OK if the update operation can be performed
152+
/// normally, regardless of whether we could update the Edge WebView2
153+
/// Runtime. If an unexpected error interrupts the update operation, error
154+
/// code of that unexpected error would be set as `errorCode`.
155+
/// When update operation can be performed normally, but update resulted in
156+
/// failure, like download failed, the error code would be presented as
157+
/// `UpdateError` property of ICoreWebView2ExperimentalUpdateRuntimeResult.
158+
HRESULT Invoke([in] HRESULT errorCode,
159+
[in] ICoreWebView2ExperimentalUpdateRuntimeResult * result);
160+
}
161+
162+
/// This interface is an extension of the ICoreWebView2Environment. An object
163+
/// implementing the ICoreWebView2ExperimentalEnvironment3 interface will also
164+
/// implement ICoreWebView2Environment.
165+
[uuid(9A2BE885-7F0B-4B26-B6DD-C969BAA00BF1), object, pointer_default(unique)]
166+
interface ICoreWebView2ExperimentalEnvironment3 : IUnknown {
167+
/// Try to update installed Microsoft Edge WebView2 Runtime.
168+
/// This will potentially result in a new version of the Edge Webview2
169+
/// Runtime being installed and `NewBrowserVersionAvailable` event fired.
170+
/// There is no guarantee on the order of that event being fired and
171+
/// TryUpdateRuntimeis completed handler being invoked. Besides the
172+
/// `NewBrowserVersionAvailable` event, there will be no impact to any
173+
/// currently running WebViews when update is installed.
174+
/// The latest version can always be queried using
175+
/// `GetAvailableCoreWebView2BrowserVersionString` API.
176+
/// This is only supported for installed Edge WebView2 Runtime. When running
177+
/// fixed version Edge WebView2 Runtime or non stable channel Edge browser,
178+
/// this API will return `HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)`.
179+
/// There could only be one active TryUpdateRuntime operation, calling the API
180+
/// before completed handler for previous call is invoked will fail with
181+
/// `HRESULT_FROM_WIN32(ERROR_BUSY)`.
182+
/// Calling the API repeatedly in a short period of time, will also fail with
183+
/// `HRESULT_FROM_WIN32(ERROR_BUSY)`.
184+
/// The TryUpdateRuntime operation is associated with the CoreWebView2Environment
185+
/// object, on going TryUpdateRuntime operation will be aborted when the
186+
/// associated CoreWebView2Environment along with the CoreWebView2 objects that
187+
/// are created by the CoreWebView2Environment object are all released.
188+
///
189+
/// \snippet AppWindow.cpp UpdateRuntime
190+
HRESULT TryUpdateRuntime(
191+
[in] ICoreWebView2ExperimentalTryUpdateRuntimeCompletedHandler *
192+
handler);
193+
}
194+
195+
```
196+
## .NET WinRT
197+
```c#
198+
namespace Microsoft.Web.WebView2.Core
199+
{
200+
public enum CoreWebView2RuntimeUpdateStatus
201+
{
202+
NoUpdate = 0,
203+
Updated = 1,
204+
BlockedByPolicy = 2,
205+
Failed = 3,
206+
}
207+
208+
public partial class CoreWebView2UpdateRuntimeResult
209+
{
210+
public CoreWebView2RuntimeUpdateStatus UpdateRuntimeStatus
211+
{
212+
get;
213+
}
214+
public int UpdateError
215+
{
216+
get;
217+
}
218+
}
219+
220+
public partial class CoreWebView2Environment
221+
{
222+
public async Task<CoreWebView2UpdateRuntimeResult> TryUpdateRuntimeAsync();
223+
}
224+
}
225+
```

0 commit comments

Comments
 (0)