Web content in WebView2 is generally subject to the same Web Platform restrictions as in the Microsoft Edge browser. However, some of the scenarios for WebView2 applications differ from the scenarios in the browser. For this reason, we're providing a set of APIs to fine-tune performance of scripts running in WebView2. These APIs allow WebView2 applications to achieve two things:
- Customize script timers (
setTimeoutandsetInterval) throttling under different page states (foreground, background, and background with intensive throttling) - Throttle script timers in select hosted iframes
Throttling Control APIs allow you to throttle JavaScript timers in scenarios where the WebView2 control in your application needs to remain visible, but consume less resources, for example, when the user is not interactive.
void OnNoUserInteraction()
{
// User is not interactive, keep webview visible but throttle timers to 500ms.
webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 500;
}
void OnUserInteraction()
{
// User is interactive again, unthrottle foreground timers.
webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 0;
}void ScenarioThrottlingControl::OnNoUserInteraction()
{
wil::com_ptr<ICoreWebView2Settings> settings;
m_webview->get_Settings(&settings);
auto settings2 = settings.try_query<ICoreWebView2Settings9>();
CHECK_FEATURE_RETURN_EMPTY(settings2);
// User is not interactive, keep webview visible but throttle timers to
// 500ms.
CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceForeground(500));
}
void ScenarioThrottlingControl::OnUserInteraction()
{
wil::com_ptr<ICoreWebView2Settings> settings;
m_webview->get_Settings(&settings);
auto settings2 = settings.try_query<ICoreWebView2Settings9>();
CHECK_FEATURE_RETURN_EMPTY(settings2);
// User is interactive again, unthrottle foreground timers.
CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceForeground(0));
}Unthrottle timers in hidden WebView
Throttling Control APIs allow you to set a custom throttling interval for timers on hidden WebViews. For example, if there's logic in your app that runs in JavaScript but doesn't need to render content, you can keep the WebView hidden and unthrottle its timers.
void SetupHiddenWebViewCore()
{
// This WebView2 will remain hidden but needs to keep running timers.
// Unthrottle background timers.
webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceBackground = 0;
// Effectively disable intensive throttling by overriding its timer interval.
webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceIntensive = 0;
webView.Visibility = System.Windows.Visibility.Hidden;
}
void DisableHiddenWebViewCore()
{
webView.Visibility = System.Windows.Visibility.Visible;
webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceBackground = 1000;
webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceIntensive = 60000;
}void ScenarioThrottlingControl::SetupHiddenWebViewCore()
{
wil::com_ptr<ICoreWebView2Settings> settings;
m_webview->get_Settings(&settings);
auto settings2 = settings.try_query<ICoreWebView2Settings9>();
CHECK_FEATURE_RETURN_EMPTY(settings2);
// This WebView2 will remain hidden but needs to keep running timers.
// Unthrottle background timers.
CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceBackground(0));
// Effectively disable intensive throttling by overriding its timer interval.
CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceIntensive(0));
CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(FALSE));
}
void ScenarioThrottlingControl::DisableHiddenWebViewCore()
{
CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(TRUE));
wil::com_ptr<ICoreWebView2Settings> settings;
m_webview->get_Settings(&settings);
auto settings2 = settings.try_query<ICoreWebView2Settings9>();
CHECK_FEATURE_RETURN_EMPTY(settings2);
CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceBackground(1000));
CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceIntensive(60000));
}Throttling Control APIs allow you to throttle timers in specific frames within the WebView2 control. For example, if your application uses iframes to host 3rd party content, you can select and mark these frames to be throttled separately from the main frame and other regular, unmarked frames.
void SetupIsolatedFramesHandler()
{
// You can use the frame properties to determine whether it should be
// marked to be throttled separately from main frame.
webView.CoreWebView2.FrameCreated += (sender, args) =>
{
if (args.Frame.Name == "isolated")
{
args.Frame.ShouldUseIsolatedThrottling = true;
}
};
webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceIsolated = 500;
}void ScenarioThrottlingControl::SetupIsolatedFramesHandler()
{
auto webview4 = m_webview.try_query<ICoreWebView2_4>();
CHECK_FEATURE_RETURN_EMPTY(webview4);
// You can use the frame properties to determine whether it should be
// marked to be throttled separately from main frame.
CHECK_FAILURE(webview4->add_FrameCreated(
Callback<ICoreWebView2FrameCreatedEventHandler>(
[this](ICoreWebView2* sender, ICoreWebView2FrameCreatedEventArgs* args) -> HRESULT
{
wil::com_ptr<ICoreWebView2Frame> webviewFrame;
CHECK_FAILURE(args->get_Frame(&webviewFrame));
auto webviewFrame6 =
webviewFrame.try_query<ICoreWebView2Frame6>();
CHECK_FEATURE_RETURN_HRESULT(webviewFrame6);
wil::unique_cotaskmem_string name;
CHECK_FAILURE(webviewFrame->get_Name(&name));
if (wcscmp(name.get(), L"isolated") == 0)
{
CHECK_FAILURE(webviewFrame6->put_ShouldUseIsolatedThrottling(TRUE));
}
return S_OK;
})
.Get(),
&m_frameCreatedToken));
wil::com_ptr<ICoreWebView2Settings> settings;
m_webview->get_Settings(&settings);
auto settings2 = settings.try_query<ICoreWebView2Settings9>();
CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceIsolated(500));
}/// A continuation of the `ICoreWebView2Settings` interface to support
/// ThrottlingPreference.
[uuid(00f1b5fb-91ed-4722-9404-e0f8fd1e6b0a), object, pointer_default(unique)]
interface ICoreWebView2Settings9 : ICoreWebView2Settings8 {
/// The preferred wake up interval (in milliseconds) to use for throttleable
/// JavaScript tasks (`setTimeout` and `setInterval`), when the WebView is in
/// foreground state. A WebView is in foreground state when its `IsVisible`
/// property is `TRUE`.
///
/// A wake up interval is the amount of time that needs to pass before the
/// WebView2 Runtime checks for new timer tasks to run.
///
/// The WebView2 Runtime will try to respect the preferred interval set by the
/// application, but the effective value will be constrained by resource and
/// platform limitations. Setting a value of `0` means a preference of no
/// throttling to be applied. The default value is a constant determined by
/// the running version of the WebView2 Runtime.
///
/// For example, an application might use a foreground value of 30 ms for
/// moderate throttling scenarios, or match the default background value
/// (usually 1000 ms).
[propget] HRESULT ThrottlingIntervalPreferenceForeground([out, retval] UINT32* value);
/// Sets the `ThrottlingIntervalPreferenceForeground` property.
[propput] HRESULT ThrottlingIntervalPreferenceForeground([in] UINT32 value);
/// The preferred wake up interval (in milliseconds) to use for throttleable
/// JavaScript tasks (`setTimeout` and `setInterval`), when the WebView is in
/// background state, with no intensive throttling. A WebView is in background
/// state when its `IsVisible` property is `FALSE`. Intensive throttling is a
/// substate of background state. For more details about intensive throttling,
/// see [Intensive throttling of Javascript timer wake ups](https://chromestatus.com/feature/4718288976216064).
///
/// A wake up interval is the amount of time that needs to pass before the
/// WebView2 Runtime checks for new timer tasks to run.
///
/// The WebView2 Runtime will try to respect the preferred interval set by the
/// application, but the effective value will be constrained by resource and
/// platform limitations. Setting a value of `0` means a preference of no
/// throttling to be applied. The default value is a constant determined by
/// the running version of the WebView2 Runtime. All other background state
/// policies (including intensive throttling) are effective independently of
/// this setting.
///
/// For example, an application might use a background value of 100 ms to
/// relax the default background value (usually 1000 ms).
[propget] HRESULT ThrottlingIntervalPreferenceBackground([out, retval] UINT32* value);
/// Sets the `ThrottlingIntervalPreferenceBackground` property.
[propput] HRESULT ThrottlingIntervalPreferenceBackground([in] UINT32 value);
/// The preferred wake up interval (in milliseconds) to use for throttleable
/// JavaScript tasks (`setTimeout` and `setInterval`), when the WebView is in
/// background state with intensive throttling. Intensive throttling is a
/// substate of background state. For more details about intensive
/// throttling, see
/// [Intensive throttling of Javascript timer wake ups](https://chromestatus.com/feature/4718288976216064).
///
/// A wake up interval is the amount of time that needs to pass before the
/// WebView2 Runtime checks for new timer tasks to run.
///
/// The WebView2 Runtime will try to respect the preferred interval set by the
/// application, but the effective value will be constrained by resource and
/// platform limitations. Setting a value of `0` means a preference of no
/// throttling to be applied. The default value is a constant determined by
/// the running version of the WebView2 Runtime.
[propget] HRESULT ThrottlingIntervalPreferenceIntensive([out, retval] UINT32* value);
/// Sets the `ThrottlingIntervalPreferenceIntensive` property.
[propput] HRESULT ThrottlingIntervalPreferenceIntensive([in] UINT32 value);
/// The preferred wake up interval (in milliseconds) to use for throttleable
/// JavaScript tasks (`setTimeout` and `setInterval`), in frames whose
/// `ShouldUseIsolatedThrottling` property is set to `TRUE`. This is a category
/// specific to WebView2 with no corresponding state in the Chromium tab state
/// model.
///
/// A wake up interval is the amount of time that needs to pass before the
/// WebView2 Runtime checks for new timer tasks to run.
///
/// The WebView2 Runtime will try to respect the preferred interval set by the
/// application, but the effective value will be constrained by resource and
/// platform limitations. Setting a value of `0` means a preference of no
/// throttling to be applied. The default value is a constant determined by
/// the running version of the WebView2 Runtime.
///
/// For example, an application might use an isolated throttling value of 30
/// ms to reduce resource consumption from third party frames in the WebView.
[propget] HRESULT ThrottlingIntervalPreferenceIsolated([out, retval] UINT32* value);
/// Sets the `ThrottlingIntervalPreferenceIsolated` property.
[propput] HRESULT ThrottlingIntervalPreferenceIsolated([in] UINT32 value);
}
/// A continuation of the `ICoreWebView2Frame` interface to support
/// ShouldUseIsolatedThrottling property.
[uuid(5b7d1b96-699b-44a2-b9f1-b8e88f9ac2be), object, pointer_default(unique)]
interface ICoreWebView2Frame6 : ICoreWebView2Frame5 {
/// Indicates whether the frame has been marked for isolated throttling by the
/// host app. When `TRUE`, the frame will receive the throttling interval set
/// by `ThrottlingIntervalPreferenceIsolated`. When `FALSE`, and for main
/// frame, throttling interval will be determined by page state and the
/// interval through their corresponding properties in the
/// `CoreWebView2Settings` object. Defaults to `FALSE` unless set otherwise.
[propget] HRESULT ShouldUseIsolatedThrottling([out, retval] BOOL* value);
/// Sets the `ShouldUseIsolatedThrottling` property.
[propput] HRESULT ShouldUseIsolatedThrottling([in] BOOL value);
}
namespace Microsoft.Web.WebView2.Core
{
runtimeclass CoreWebView2
{
// ...
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings9")]
{
UInt32 ThrottlingIntervalPreferenceForeground { get; set; };
UInt32 ThrottlingIntervalPreferenceBackground { get; set; };
UInt32 ThrottlingIntervalPreferenceIntensive { get; set; };
UInt32 ThrottlingIntervalPreferenceIsolated { get; set; };
}
}
runtimeclass CoreWebView2Frame
{
// ...
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Frame6")]
{
Boolean ShouldUseIsolatedThrottling { get; set; };
}
}
}