From 03831fba43139b84a68e2f60db40d8884da62e23 Mon Sep 17 00:00:00 2001 From: Luis Flores Date: Tue, 7 Nov 2023 18:06:25 -0800 Subject: [PATCH 1/6] Add spec file --- specs/ThrottlingControlScript.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 specs/ThrottlingControlScript.md diff --git a/specs/ThrottlingControlScript.md b/specs/ThrottlingControlScript.md new file mode 100644 index 000000000..63db61288 --- /dev/null +++ b/specs/ThrottlingControlScript.md @@ -0,0 +1,12 @@ +Throttling Control - Script Throttling +=== + +# Background + +# Conceptual pages (How To) + +# Examples + +# API Details + +# Appendix From 84a31c03010db3eed43ddf7aca70c942fb9ff6ec Mon Sep 17 00:00:00 2001 From: Luis Flores Date: Wed, 8 Nov 2023 16:03:05 -0800 Subject: [PATCH 2/6] Add Throttling Control spec baseline draft --- specs/ThrottlingControlScript.md | 253 ++++++++++++++++++++++++++++++- 1 file changed, 252 insertions(+), 1 deletion(-) diff --git a/specs/ThrottlingControlScript.md b/specs/ThrottlingControlScript.md index 63db61288..dcece6796 100644 --- a/specs/ThrottlingControlScript.md +++ b/specs/ThrottlingControlScript.md @@ -2,11 +2,262 @@ Throttling Control - Script Throttling === # Background +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: -# Conceptual pages (How To) +* Customize script timers throttling under different page states (foreground, background, and background with intensive throttling) +* Throttle script timers in select hosted iframes # Examples +## Throttle timers in visible WebView + +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. + +```c# +void OnNoUserInteraction() +{ + // User is not interactive, keep webview visible but throttle timers to 500ms. + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Foreground, 500); +} + +void OnUserInteraction() +{ + // User is interactive again, unthrottle foreground timers. + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Foreground, 0); +} +``` + +```cpp +void ScenarioThrottlingControl::OnNoUserInteraction() +{ + auto webView21 = m_webview.try_query(); + CHECK_FEATURE_RETURN_EMPTY(webView21); + + // User is not interactive, keep webview visible but throttle timers to + // 500ms. + CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( + COREWEBVIEW2_THROTTLING_PRIORITY_FOREGROUND, 500)); +} + +void ScenarioThrottlingControl::OnUserInteraction() +{ + auto webView21 = m_webview.try_query(); + CHECK_FEATURE_RETURN_EMPTY(webView21); + + // User is interactive again, unthrottle foreground timers. + CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( + COREWEBVIEW2_THROTTLING_PRIORITY_FOREGROUND, 0)); +} +``` + +## Unthrottle timers in hidden WebView + +Throttling 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. + +```C# +void SetupHiddenWebViewCore() +{ + // This WebView2 will remain hidden but needs to keep running timers. + // Unthrottle background timers. + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Background, 0); + // Effectively disable intensive throttling by overriding its timer interval. + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Intensive, 0); + webView.Visibility = System.Windows.Visibility.Hidden; +} + +void DisableHiddenWebViewCore() +{ + webView.Visibility = System.Windows.Visibility.Visible; + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Background, 1000); + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Intensive, 60000); +} +``` + +```cpp +void ScenarioThrottlingControl::SetupHiddenWebViewCore() +{ + auto webView21 = m_webview.try_query(); + 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_PRIORITY_BACKGROUND, 0)); + // Effectively disable intensive throttling by overriding its timer interval. + CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( + COREWEBVIEW2_THROTTLING_PRIORITY_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(); + CHECK_FEATURE_RETURN_EMPTY(webView21); + + CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( + COREWEBVIEW2_THROTTLING_PRIORITY_BACKGROUND, 1000)); + CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( + COREWEBVIEW2_THROTTLING_PRIORITY_INTENSIVE, 60000)); +} +``` + +## Throttle timers in hosted iframes + +Throttling 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 regular, unmarked frames. + +```C# +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(CoreWebView2ThrottlingPriority.UntrustedFrame, 500); +} +``` + +```cpp +void ScenarioThrottlingControl::SetupUntrustedFramesHandler() +{ + auto webview4 = m_webview.try_query(); + 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( + [this](ICoreWebView2* sender, ICoreWebView2FrameCreatedEventArgs* args) -> HRESULT + { + wil::com_ptr webviewFrame; + CHECK_FAILURE(args->get_Frame(&webviewFrame)); + + auto webviewFrame6 = + webviewFrame.try_query(); + 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 webViewStaging21 = m_webview.try_query(); + CHECK_FAILURE(webViewStaging21->SetThrottlingIntervalPreference( + COREWEBVIEW2_THROTTLING_PRIORITY_UNTRUSTED_FRAME, 500)); +} +``` + # API Details +```cpp +[v1_enum] +typedef enum COREWEBVIEW2_THROTTLING_PRIORITY { + /// Applies to frames whose WebView is in foreground state. The default value + /// is determined by the WebView2 Runtime. + COREWEBVIEW2_THROTTLING_PRIORITY_FOREGROUND, + + /// Applies to frames whose WebView is in background state. The default value + /// is determined by the WebView2 Runtime. All other background state policies + /// (including intensive throttling) are effective independently of this + /// setting. + COREWEBVIEW2_THROTTLING_PRIORITY_BACKGROUND, + + /// Applies to frames whose WebView is being intensively throttled. The + /// default value is determined by the WebView2 Runtime. + COREWEBVIEW2_THROTTLING_PRIORITY_INTENSIVE, + + /// Applies to frames that have been marked untrusted by the host app. + /// This is a priority specific to WebView2 with no corresponding state in the + /// Chromium tab state model. The default value is determined by the WebView2 + /// Runtime. + COREWEBVIEW2_THROTTLING_PRIORITY_UNTRUSTED_FRAME +} COREWEBVIEW2_THROTTLING_PRIORITY; + +/// 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, for the given throttling priority. Default values + /// are determined by the WebView2 Runtime. + HRESULT GetThrottlingIntervalPreference( + [in] COREWEBVIEW2_THROTTLING_PRIORITY priority, + [out, retval] UINT32* interval); + /// Sets the preferred wake up interval (in milliseconds) for throttleable + /// JavaScript tasks, for the given throttling priority. The value can be freely + /// chosen by the application. 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). Setting a value of `0` means + /// no throttling will be applied, but the effective interval can still be + /// constrained by resource and platform limitations. + HRESULT SetThrottlingIntervalPreference( + [in] COREWEBVIEW2_THROTTLING_PRIORITY const priority, + [in] UINT32 interval); +} + +/// 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 priority as compared to regular frames. Defaults to + /// `FALSE` unless set otherwise. When `FALSE`, and for main frame, throttling + /// priority 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); +} + +``` + +```C# +namespace Microsoft.Web.WebView2.Core +{ + enum CoreWebView2ThrottlingPriority + { + Foreground = 0, + Background = 1, + Intensive = 2, + UntrustedFrame = 3, + }; + + runtimeclass CoreWebView2 + { + // ... + + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_21")] + { + UInt32 GetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority priority); + + void SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority priority, UInt32 interval); + } + } + + runtimeclass CoreWebView2Frame + { + // ... + + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Frame6")] + { + Boolean IsUntrusted { get; set; }; + } + } +} + +``` # Appendix From bb4deeec6ebec812db6101540d48e34be8150271 Mon Sep 17 00:00:00 2001 From: Luis Flores Date: Fri, 10 Nov 2023 13:20:02 -0800 Subject: [PATCH 3/6] Update from ADO PR feedback --- specs/ThrottlingControlScript.md | 123 +++++++++++++++++-------------- 1 file changed, 68 insertions(+), 55 deletions(-) diff --git a/specs/ThrottlingControlScript.md b/specs/ThrottlingControlScript.md index dcece6796..d70fd0626 100644 --- a/specs/ThrottlingControlScript.md +++ b/specs/ThrottlingControlScript.md @@ -4,7 +4,7 @@ Throttling Control - Script Throttling # Background 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 throttling under different page states (foreground, background, and background with intensive throttling) +* Customize script timers (`setTimeout` and `setInterval`) throttling under different page states (foreground, background, and background with intensive throttling) * Throttle script timers in select hosted iframes # Examples @@ -17,13 +17,13 @@ Throttling Control APIs allow you to throttle JavaScript timers in scenarios whe void OnNoUserInteraction() { // User is not interactive, keep webview visible but throttle timers to 500ms. - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Foreground, 500); + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Foreground, 500); } void OnUserInteraction() { // User is interactive again, unthrottle foreground timers. - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Foreground, 0); + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Foreground, 0); } ``` @@ -36,7 +36,7 @@ void ScenarioThrottlingControl::OnNoUserInteraction() // User is not interactive, keep webview visible but throttle timers to // 500ms. CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_PRIORITY_FOREGROUND, 500)); + COREWEBVIEW2_THROTTLING_CATEGORY_FOREGROUND, 500)); } void ScenarioThrottlingControl::OnUserInteraction() @@ -46,30 +46,30 @@ void ScenarioThrottlingControl::OnUserInteraction() // User is interactive again, unthrottle foreground timers. CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_PRIORITY_FOREGROUND, 0)); + COREWEBVIEW2_THROTTLING_CATEGORY_FOREGROUND, 0)); } ``` ## Unthrottle timers in hidden WebView -Throttling 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. +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. ```C# void SetupHiddenWebViewCore() { // This WebView2 will remain hidden but needs to keep running timers. // Unthrottle background timers. - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Background, 0); + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Background, 0); // Effectively disable intensive throttling by overriding its timer interval. - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Intensive, 0); + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Intensive, 0); webView.Visibility = System.Windows.Visibility.Hidden; } void DisableHiddenWebViewCore() { webView.Visibility = System.Windows.Visibility.Visible; - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Background, 1000); - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.Intensive, 60000); + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Background, 1000); + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Intensive, 60000); } ``` @@ -82,10 +82,10 @@ void ScenarioThrottlingControl::SetupHiddenWebViewCore() // This WebView2 will remain hidden but needs to keep running timers. // Unthrottle background timers. CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_PRIORITY_BACKGROUND, 0)); + COREWEBVIEW2_THROTTLING_CATEGORY_BACKGROUND, 0)); // Effectively disable intensive throttling by overriding its timer interval. CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_PRIORITY_INTENSIVE, 0)); + COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE, 0)); CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(FALSE)); } @@ -98,15 +98,15 @@ void ScenarioThrottlingControl::DisableHiddenWebViewCore() CHECK_FEATURE_RETURN_EMPTY(webView21); CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_PRIORITY_BACKGROUND, 1000)); + COREWEBVIEW2_THROTTLING_CATEGORY_BACKGROUND, 1000)); CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_PRIORITY_INTENSIVE, 60000)); + COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE, 60000)); } ``` ## Throttle timers in hosted iframes -Throttling 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 regular, unmarked frames. +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. ```C# void SetupUntrustedFramesHandler() @@ -121,7 +121,7 @@ void SetupUntrustedFramesHandler() } }; - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority.UntrustedFrame, 500); + webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.UntrustedFrame, 500); } ``` @@ -156,56 +156,68 @@ void ScenarioThrottlingControl::SetupUntrustedFramesHandler() .Get(), &m_frameCreatedToken)); - auto webViewStaging21 = m_webview.try_query(); - CHECK_FAILURE(webViewStaging21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_PRIORITY_UNTRUSTED_FRAME, 500)); + auto webView21 = m_webview.try_query(); + CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( + COREWEBVIEW2_THROTTLING_CATEGORY_UNTRUSTED_FRAME, 500)); } ``` # API Details ```cpp [v1_enum] -typedef enum COREWEBVIEW2_THROTTLING_PRIORITY { - /// Applies to frames whose WebView is in foreground state. The default value - /// is determined by the WebView2 Runtime. - COREWEBVIEW2_THROTTLING_PRIORITY_FOREGROUND, - - /// Applies to frames whose WebView is in background state. The default value - /// is determined by the WebView2 Runtime. All other background state policies - /// (including intensive throttling) are effective independently of this - /// setting. - COREWEBVIEW2_THROTTLING_PRIORITY_BACKGROUND, - - /// Applies to frames whose WebView is being intensively throttled. The - /// default value is determined by the WebView2 Runtime. - COREWEBVIEW2_THROTTLING_PRIORITY_INTENSIVE, +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 priority specific to WebView2 with no corresponding state in the - /// Chromium tab state model. The default value is determined by the WebView2 - /// Runtime. - COREWEBVIEW2_THROTTLING_PRIORITY_UNTRUSTED_FRAME -} COREWEBVIEW2_THROTTLING_PRIORITY; + /// 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, for the given throttling priority. Default values - /// are determined by the WebView2 Runtime. + /// 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_PRIORITY priority, - [out, retval] UINT32* interval); + [in] COREWEBVIEW2_THROTTLING_CATEGORY category, + [out, retval] UINT32* intervalInMilliseconds); + /// Sets the preferred wake up interval (in milliseconds) for throttleable - /// JavaScript tasks, for the given throttling priority. The value can be freely - /// chosen by the application. 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). Setting a value of `0` means - /// no throttling will be applied, but the effective interval can still be - /// constrained by resource and platform limitations. + /// 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_PRIORITY const priority, - [in] UINT32 interval); + [in] COREWEBVIEW2_THROTTLING_CATEGORY category, + [in] UINT32 intervalInMilliseconds); } /// A continuation of the `ICoreWebView2Frame` interface to support IsUntrusted property. @@ -213,11 +225,12 @@ interface ICoreWebView2_21 : ICoreWebView2_20 { 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 priority as compared to regular frames. Defaults to + /// script throttling category as compared to regular frames. Defaults to /// `FALSE` unless set otherwise. When `FALSE`, and for main frame, throttling - /// priority will be determined by page state. The corresponding preferred + /// 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); } @@ -227,7 +240,7 @@ interface ICoreWebView2Frame6 : ICoreWebView2Frame5 { ```C# namespace Microsoft.Web.WebView2.Core { - enum CoreWebView2ThrottlingPriority + enum CoreWebView2ThrottlingCategory { Foreground = 0, Background = 1, @@ -241,9 +254,9 @@ namespace Microsoft.Web.WebView2.Core [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_21")] { - UInt32 GetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority priority); + UInt32 GetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory category); - void SetThrottlingIntervalPreference(CoreWebView2ThrottlingPriority priority, UInt32 interval); + void SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory category, UInt32 intervalInMilliseconds); } } From 855667f7d5f586d828c4f7de5ac21ee476348847 Mon Sep 17 00:00:00 2001 From: Luis Flores Date: Fri, 10 Nov 2023 13:22:07 -0800 Subject: [PATCH 4/6] Add linebreaks --- specs/ThrottlingControlScript.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/specs/ThrottlingControlScript.md b/specs/ThrottlingControlScript.md index d70fd0626..2bc9f8572 100644 --- a/specs/ThrottlingControlScript.md +++ b/specs/ThrottlingControlScript.md @@ -2,16 +2,25 @@ Throttling Control - Script Throttling === # Background -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 (`setTimeout` and `setInterval`) throttling under different page states (foreground, background, and background with intensive throttling) +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 (`setTimeout` and `setInterval`) throttling under +different page states (foreground, background, and background with intensive +throttling) * Throttle script timers in select hosted iframes # Examples ## Throttle timers in visible WebView -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. +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. ```c# void OnNoUserInteraction() @@ -52,7 +61,10 @@ void ScenarioThrottlingControl::OnUserInteraction() ## 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. +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. ```C# void SetupHiddenWebViewCore() @@ -106,7 +118,10 @@ void ScenarioThrottlingControl::DisableHiddenWebViewCore() ## Throttle timers in hosted iframes -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. +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. ```C# void SetupUntrustedFramesHandler() From e6e1466719864dfd447e13d72bacf8afa0bd259f Mon Sep 17 00:00:00 2001 From: Luis Flores Date: Tue, 14 Nov 2023 18:52:29 -0800 Subject: [PATCH 5/6] PR feedback: rename IsUntrusted->ShouldUseIsolatedThrottling --- specs/ThrottlingControlScript.md | 48 +++++++++++++++++--------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/specs/ThrottlingControlScript.md b/specs/ThrottlingControlScript.md index 2bc9f8572..647ec0895 100644 --- a/specs/ThrottlingControlScript.md +++ b/specs/ThrottlingControlScript.md @@ -124,15 +124,15 @@ party content, you can select and mark these frames to be throttled separately from the main frame and other regular, unmarked frames. ```C# -void SetupUntrustedFramesHandler() +void SetupIsolatedFramesHandler() { 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") + if (args.Frame.Name == "isolated") { - args.Frame.IsUntrusted = true; + args.Frame.ShouldUseIsolatedThrottling = true; } }; @@ -141,7 +141,7 @@ void SetupUntrustedFramesHandler() ``` ```cpp -void ScenarioThrottlingControl::SetupUntrustedFramesHandler() +void ScenarioThrottlingControl::SetupIsolatedFramesHandler() { auto webview4 = m_webview.try_query(); CHECK_FEATURE_RETURN_EMPTY(webview4); @@ -161,9 +161,9 @@ void ScenarioThrottlingControl::SetupUntrustedFramesHandler() wil::unique_cotaskmem_string name; CHECK_FAILURE(webviewFrame->get_Name(&name)); - if (wcscmp(name.get(), L"untrusted") == 0) + if (wcscmp(name.get(), L"isolated") == 0) { - CHECK_FAILURE(webviewFrame6->put_IsUntrusted(TRUE)); + CHECK_FAILURE(webviewFrame6->put_ShouldUseIsolatedThrottling(TRUE)); } return S_OK; @@ -173,7 +173,7 @@ void ScenarioThrottlingControl::SetupUntrustedFramesHandler() auto webView21 = m_webview.try_query(); CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_CATEGORY_UNTRUSTED_FRAME, 500)); + COREWEBVIEW2_THROTTLING_CATEGORY_ISOLATED, 500)); } ``` @@ -200,11 +200,11 @@ typedef enum COREWEBVIEW2_THROTTLING_CATEGORY { /// WebView2 Runtime. COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE, - /// Applies to frames that have been marked untrusted by the host app. + /// Applies to frames that have been marked for isolated throttling 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_ISOLATED } COREWEBVIEW2_THROTTLING_CATEGORY; /// A continuation of the `ICoreWebView2` interface to support ThrottlingPreference. @@ -228,26 +228,28 @@ interface ICoreWebView2_21 : ICoreWebView2_20 { /// 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. + /// resource and platform limitations. Setting a value of `0` means a + /// preference of no throttling to be applied. HRESULT SetThrottlingIntervalPreference( [in] COREWEBVIEW2_THROTTLING_CATEGORY category, [in] UINT32 intervalInMilliseconds); } -/// A continuation of the `ICoreWebView2Frame` interface to support IsUntrusted property. +/// A continuation of the `ICoreWebView2Frame` interface to support +/// ShouldUseIsolatedThrottling 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); + /// The `ShouldUseIsolatedThrottling` property indicates whether the frame has + /// been marked for isolated throttling by the host app. Isolated throttling + /// 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 ShouldUseIsolatedThrottling([out, retval] BOOL* value); + + /// Marks the frame for isolated script throttling. + [propput] HRESULT ShouldUseIsolatedThrottling([in] BOOL value); } ``` @@ -281,7 +283,7 @@ namespace Microsoft.Web.WebView2.Core [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Frame6")] { - Boolean IsUntrusted { get; set; }; + Boolean ShouldUseIsolatedThrottling { get; set; }; } } } From a477d2022aaa84948c738f3b932747c386177123 Mon Sep 17 00:00:00 2001 From: Luis Flores Date: Wed, 15 Nov 2023 15:46:36 -0800 Subject: [PATCH 6/6] PR feedback: move throttling preference to settings as properties --- specs/ThrottlingControlScript.md | 240 +++++++++++++++++-------------- 1 file changed, 136 insertions(+), 104 deletions(-) diff --git a/specs/ThrottlingControlScript.md b/specs/ThrottlingControlScript.md index 647ec0895..08b6fa1ec 100644 --- a/specs/ThrottlingControlScript.md +++ b/specs/ThrottlingControlScript.md @@ -26,36 +26,38 @@ 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); + webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 500; } void OnUserInteraction() { // User is interactive again, unthrottle foreground timers. - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Foreground, 0); + webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceForeground = 0; } ``` ```cpp void ScenarioThrottlingControl::OnNoUserInteraction() { - auto webView21 = m_webview.try_query(); - CHECK_FEATURE_RETURN_EMPTY(webView21); + wil::com_ptr settings; + m_webview->get_Settings(&settings); + auto settings2 = settings.try_query(); + CHECK_FEATURE_RETURN_EMPTY(settings2); // User is not interactive, keep webview visible but throttle timers to // 500ms. - CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_CATEGORY_FOREGROUND, 500)); + CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceForeground(500)); } void ScenarioThrottlingControl::OnUserInteraction() { - auto webView21 = m_webview.try_query(); - CHECK_FEATURE_RETURN_EMPTY(webView21); + wil::com_ptr settings; + m_webview->get_Settings(&settings); + auto settings2 = settings.try_query(); + CHECK_FEATURE_RETURN_EMPTY(settings2); // User is interactive again, unthrottle foreground timers. - CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_CATEGORY_FOREGROUND, 0)); + CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceForeground(0)); } ``` @@ -71,33 +73,33 @@ void SetupHiddenWebViewCore() { // This WebView2 will remain hidden but needs to keep running timers. // Unthrottle background timers. - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Background, 0); + webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceBackground = 0; // Effectively disable intensive throttling by overriding its timer interval. - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.Intensive, 0); + webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceIntensive = 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); + webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceBackground = 1000; + webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceIntensive = 60000; } ``` ```cpp void ScenarioThrottlingControl::SetupHiddenWebViewCore() { - auto webView21 = m_webview.try_query(); - CHECK_FEATURE_RETURN_EMPTY(webView21); + wil::com_ptr settings; + m_webview->get_Settings(&settings); + auto settings2 = settings.try_query(); + CHECK_FEATURE_RETURN_EMPTY(settings2); // This WebView2 will remain hidden but needs to keep running timers. // Unthrottle background timers. - CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_CATEGORY_BACKGROUND, 0)); + CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceBackground(0)); // Effectively disable intensive throttling by overriding its timer interval. - CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE, 0)); + CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceIntensive(0)); CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(FALSE)); } @@ -106,13 +108,13 @@ void ScenarioThrottlingControl::DisableHiddenWebViewCore() { CHECK_FAILURE(m_appWindow->GetWebViewController()->put_IsVisible(TRUE)); - auto webView21 = m_webview.try_query(); - CHECK_FEATURE_RETURN_EMPTY(webView21); + wil::com_ptr settings; + m_webview->get_Settings(&settings); + auto settings2 = settings.try_query(); + CHECK_FEATURE_RETURN_EMPTY(settings2); - CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_CATEGORY_BACKGROUND, 1000)); - CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_CATEGORY_INTENSIVE, 60000)); + CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceBackground(1000)); + CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceIntensive(60000)); } ``` @@ -126,17 +128,17 @@ from the main frame and other regular, unmarked frames. ```C# 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) => { - // You can use the frame properties to determine whether it should be - // marked to be throttled separately from main frame. if (args.Frame.Name == "isolated") { args.Frame.ShouldUseIsolatedThrottling = true; } }; - webView.CoreWebView2.SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory.UntrustedFrame, 500); + webView.CoreWebView2.Settings.ThrottlingIntervalPreferenceIsolated = 500; } ``` @@ -171,84 +173,118 @@ void ScenarioThrottlingControl::SetupIsolatedFramesHandler() .Get(), &m_frameCreatedToken)); - auto webView21 = m_webview.try_query(); - CHECK_FAILURE(webView21->SetThrottlingIntervalPreference( - COREWEBVIEW2_THROTTLING_CATEGORY_ISOLATED, 500)); + wil::com_ptr settings; + m_webview->get_Settings(&settings); + auto settings2 = settings.try_query(); + CHECK_FAILURE(settings2->put_ThrottlingIntervalPreferenceIsolated(500)); } ``` # API Details ```cpp -[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 for isolated throttling 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_ISOLATED -} COREWEBVIEW2_THROTTLING_CATEGORY; - -/// A continuation of the `ICoreWebView2` interface to support ThrottlingPreference. +/// A continuation of the `ICoreWebView2Settings` 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 a - /// preference of no throttling to be applied. - HRESULT SetThrottlingIntervalPreference( - [in] COREWEBVIEW2_THROTTLING_CATEGORY category, - [in] UINT32 intervalInMilliseconds); +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 { - /// The `ShouldUseIsolatedThrottling` property indicates whether the frame has - /// been marked for isolated throttling by the host app. Isolated throttling - /// 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`). + /// 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); - /// Marks the frame for isolated script throttling. + /// Sets the `ShouldUseIsolatedThrottling` property. [propput] HRESULT ShouldUseIsolatedThrottling([in] BOOL value); } @@ -257,23 +293,19 @@ interface ICoreWebView2Frame6 : ICoreWebView2Frame5 { ```C# 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")] + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings9")] { - UInt32 GetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory category); + UInt32 ThrottlingIntervalPreferenceForeground { get; set; }; + + UInt32 ThrottlingIntervalPreferenceBackground { get; set; }; + + UInt32 ThrottlingIntervalPreferenceIntensive { get; set; }; - void SetThrottlingIntervalPreference(CoreWebView2ThrottlingCategory category, UInt32 intervalInMilliseconds); + UInt32 ThrottlingIntervalPreferenceIsolated { get; set; }; } }