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.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Foreground, 500);
}
void OnUserInteraction()
{
// User is interactive again, unthrottle foreground timers.
webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Foreground, 0);
}void ScenarioThrottlingControl::OnNoUserInteraction()
{
auto webView21 = m_webview.try_query<ICoreWebView2_21>();
CHECK_FEATURE_RETURN_EMPTY(webView21);
// User is not interactive, keep webview visible but throttle timers to
// 500ms.
CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
COREWEBVIEW2_THROTTLING_CATEGORY_FOREGROUND, 500));
}
void ScenarioThrottlingControl::OnUserInteraction()
{
auto webView21 = m_webview.try_query<ICoreWebView2_21>();
CHECK_FEATURE_RETURN_EMPTY(webView21);
// User is interactive again, unthrottle foreground timers.
CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
COREWEBVIEW2_THROTTLING_CATEGORY_FOREGROUND, 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.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Background, 0);
// Effectively disable intensive throttling by overriding its timer interval.
webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Intensive, 0);
webView.Visibility = System.Windows.Visibility.Hidden;
}
void DisableHiddenWebViewCore()
{
webView.Visibility = System.Windows.Visibility.Visible;
webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Background, 1000);
webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Intensive, 60000);
}void ScenarioThrottlingControl::SetupHiddenWebViewCore()
{
auto webView21 = m_webview.try_query<ICoreWebView2_21>();
CHECK_FEATURE_RETURN_EMPTY(webView21);
// This WebView2 will remain hidden but needs to keep running timers.
// Unthrottle background timers.
CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
COREWEBVIEW2_THROTTLING_CATEGORY_BACKGROUND, 0));
// Effectively disable intensive throttling by overriding its timer interval.
CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE, 0));
CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(FALSE));
}
void ScenarioThrottlingControl::DisableHiddenWebViewCore()
{
CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(TRUE));
auto webView21 = m_webview.try_query<ICoreWebView2_21>();
CHECK_FEATURE_RETURN_EMPTY(webView21);
CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
COREWEBVIEW2_THROTTLING_CATEGORY_BACKGROUND, 1000));
CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE, 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 SetupUntrustedFramesHandler()
{
webView.CoreWebView2.FrameCreated += (sender, args) =>
{
// You can use the frame properties to determine whether it should be
// marked to be throttled separately from main frame.
if (args.Frame.Name == "untrusted")
{
args.Frame.IsUntrusted = true;
}
};
webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.UntrustedFrame, 500);
}void ScenarioThrottlingControl::SetupUntrustedFramesHandler()
{
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"untrusted") == 0)
{
CHECK_FAILURE(webviewFrame6->put_IsUntrusted(TRUE));
}
return S_OK;
})
.Get(),
&m_frameCreatedToken));
auto webView21 = m_webview.try_query<ICoreWebView2_21>();
CHECK_FAILURE(webView21->SetThrottlingIntervalPreference(
COREWEBVIEW2_THROTTLING_CATEGORY_UNTRUSTED_FRAME, 500));
}[v1_enum]
typedef enum COREWEBVIEW2_THROTTLING_CATEGORY {
/// Applies to frames whose WebView is in foreground state. WebViews whose
/// `IsVisible` property is `TRUE` are in this state. The default value is a
/// constant determined by the running version of the WebView2 Runtime.
COREWEBVIEW2_THROTTLING_CATEGORY_FOREGROUND,
/// Applies to frames whose WebView is in background state. WebViews whose
/// `IsVisible` property is `FALSE` are in this state. 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.
COREWEBVIEW2_THROTTLING_CATEGORY_BACKGROUND,
/// Applies to frames whose WebView is being intensively throttled (a
/// sub-state of background state). For more details about intensive
/// throttling, see [Intensive throttling of Javascript timer wake ups](https://chromestatus.com/feature/4718288976216064).
/// The default value is a constant determined by the running version of the
/// WebView2 Runtime.
COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE,
/// Applies to frames that have been marked untrusted by the host app.
/// This is a category specific to WebView2 with no corresponding state in the
/// Chromium tab state model. The default value is a constant determined by
/// the running version of the WebView2 Runtime.
COREWEBVIEW2_THROTTLING_CATEGORY_UNTRUSTED_FRAME
} COREWEBVIEW2_THROTTLING_CATEGORY;
/// A continuation of the `ICoreWebView2` interface to support ThrottlingPreference.
[uuid(00f1b5fb-91ed-4722-9404-e0f8fd1e6b0a), object, pointer_default(unique)]
interface ICoreWebView2_21 : ICoreWebView2_20 {
/// Get the preferred wake up interval (in milliseconds) for throttleable
/// JavaScript tasks (`setTimeout` and `setInterval`), for the given
/// throttling category. 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 default interval values are constants determined by the running
/// version of the WebView2 Runtime.
HRESULT GetThrottlingIntervalPreference(
[in] COREWEBVIEW2_THROTTLING_CATEGORY category,
[out, retval] UINT32* intervalInMilliseconds);
/// Sets the preferred wake up interval (in milliseconds) for throttleable
/// JavaScript tasks (`setTimeout` and `setInterval`), for the given
/// throttling category. A wake up interval is the amount of time that needs
/// to pass before the WebView2 Runtime checks for new timer tasks to run. 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). 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 no
/// throttling will be applied.
HRESULT SetThrottlingIntervalPreference(
[in] COREWEBVIEW2_THROTTLING_CATEGORY category,
[in] UINT32 intervalInMilliseconds);
}
/// A continuation of the `ICoreWebView2Frame` interface to support IsUntrusted property.
[uuid(5b7d1b96-699b-44a2-b9f1-b8e88f9ac2be), object, pointer_default(unique)]
interface ICoreWebView2Frame6 : ICoreWebView2Frame5 {
/// The `IsUntrusted` property indicates whether the frame has been marked
/// untrusted by the host app. Untrusted frames will receive a different
/// script throttling category as compared to regular frames. Defaults to
/// `FALSE` unless set otherwise. When `FALSE`, and for main frame, throttling
/// category will be determined by page state. The corresponding preferred
/// interval will apply (set through `SetThrottlingIntervalPreference`).
[propget] HRESULT IsUntrusted([out, retval] BOOL* value);
/// Marks the frame as untrusted, for script throttling purposes.
[propput] HRESULT IsUntrusted([in] BOOL value);
}
namespace Microsoft.Web.WebView2.Core
{
enum CoreWebView2ThrottlingCategory
{
Foreground = 0,
Background = 1,
Intensive = 2,
UntrustedFrame = 3,
};
runtimeclass CoreWebView2
{
// ...
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_21")]
{
UInt32 GetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory category);
void SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory category, UInt32 intervalInMilliseconds);
}
}
runtimeclass CoreWebView2Frame
{
// ...
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Frame6")]
{
Boolean IsUntrusted { get; set; };
}
}
}