Export (0) Print
Expand All

Following resource usage rules in apps for Office

apps for Office

To provide a satisfactory experience for users of apps for Office, you must ensure that your app performs within specific limits for CPU core and memory usage, reliability and, for mail apps, the response time evaluating regular expressions. These run-time resource usage limits apply to only the supporting Office rich clients but not Excel Online, Outlook Web App or OWA for Devices. On the other hand, this topic further suggests app design and implementation techniques that apps on the desktop, tablet, and smart phone platforms can employ to control their performance.

Last modified: February 27, 2014

Applies to: Access app for SharePoint | Excel 2013 | Excel 2013 RT | Excel 2013 SP1 | Excel Online | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices | PowerPoint 2013 | PowerPoint 2013 RT | PowerPoint 2013 SP1 | PowerPoint Online | Project 2013 | Project 2013 SP1 | Word 2013 | Word 2013 RT | Word 2013 SP1

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

In this article
Resource usage limits for apps
Verifying resource usage issues in the Telemetry Log
Design and implementation techniques
Additional resources

Note Note

The resource usage limits in this section apply to only the Office rich clients that support apps for Office. In particular, in the rest of this section, "Outlook" refers to only the Outlook rich client, but not Outlook Web App.

Run-time resource usage limits safeguard reasonable performance for users. These limits also help mitigate denial-of-service attacks. You should sufficiently test your app for Office on the corresponding rich client of the host application with a wide range of possible data, measure its performance against the following limits, and tune it to perform within the stated limits. The following lists the run-time resource usage limits that apply to all types of apps for Office:

  • CPU core usage—A single CPU core usage threshold of 90%, observed three times in default 5-second intervals.

    The default interval for a host rich client to check CPU core usage is every 5 seconds. If the host client detects the CPU core usage of an app is above the threshold value, it displays a message asking if the user wants to continue running the app. If the user chooses to continue running the app, then the host client does not ask the user again during that edit session. Administrators may wish to raise the threshold to reduce the display of this warning message if users run CPU-intensive apps. Administrators can adjust the detection interval using the key AlertInterval in the Windows registry. For more information, see Overriding resource usage settings for performance of apps for Office.

  • Memory usage—A default memory usage threshold that is dynamically determined based on the available physical memory of the device.

    By default, when a host rich client detects that physical memory usage on a device exceeds 80% of the available memory, the client starts monitoring apps memory usage, at a document level for content and task pane apps, and at a mailbox level for mail apps. At a default interval of 5 seconds, the client warns the user if physical memory usage for a set of apps at the document or mailbox level exceeds 50%. This memory usage limit uses physical rather than virtual memory to ensure good performance on devices with limited RAM such as tablets. The administrator may override this dynamic setting with an explicit limit using the MemoryAlertThreshold key as a global setting in the Windows registry.

    Administrators can also adjust the alert interval using the key AlertInterval as a global setting. For more information, see Overriding resource usage settings for performance of apps for Office.

  • Crash tolerance—A default limit of 4 crashes for an app.

    Administrators can adjust the threshold for crashes using the key RestartManagerRetryLimit as a setting in the Windows registry. For more information, see Overriding resource usage settings for performance of apps for Office.

  • Application blocking—Prolonged unresponsiveness threshold of 5 seconds perceived of an app.

    Prolonged unresponsiveness in the user interface impacts the user’s experiences at the app level and the host application level. When this occurs, the host application automatically restarts all of the active apps for a document or mailbox (where applicable), and warns the user which app became unresponsive. Apps can reach this threshold when they do not regularly yield processing while performing long-running tasks. There are techniques to ensure that blocking does not occur. Administrators cannot override this threshold.

Icon for mail apps for Office

If any mail app exceeds the preceding thresholds for CPU core or memory usage, or tolerance limit for crashes, Outlook disables the app. The Exchange Admin Center displays the disabled status of the app.

Note Note

Even though only the Outlook rich client and not Outlook Web App or OWA for Devices monitors resource usage, if the rich client disables a mail app, that app is also disabled for use in Outlook Web App and OWA for Devices.

In addition to the CPU core, memory, and reliability rules, mail apps should observe the following rules on activation:

  • Regular expressions response time—A default threshold of 1,000 milliseconds for Outlook to evaluate all regular expressions in the manifest of a mail app. Exceeding the threshold causes Outlook to retry evaluation at a later time.

    Using a group policy or application-specific setting in the Windows registry, administrators can adjust this default threshold value of 1,000 milliseconds in the OutlookActivationAlertThreshold setting. For more information, see Overriding resource usage settings for performance of apps for Office.

  • Regular expressions re-evaluation—A default limit of three times for Outlook to reevaluate all the regular expressions in a manifest. If evaluation fails all three times by exceeding the applicable threshold (which is either the default of 1,000 milliseconds or a value specified by OutlookActivationAlertThreshold, if that setting exists in the Windows registry), Outlook disables the mail app. The Exchange Admin Center displays the disabled status, and the app is disabled for use in the Outlook rich client, Outlook Web App and OWA for Devices.

    Using a group policy or application-specific setting in the Windows registry, administrators can adjust this number of times to retry evaluation in the OutlookActivationManagerRetryLimit setting. For more information, see Overriding resource usage settings for performance of apps for Office.

Icon for task pane and content apps for Office

If any content or task pane app exceeds the preceding thresholds on CPU core or memory usage, or tolerance limit for crashes, the corresponding host application displays a warning for the user. At this point, the user can do one of the following:

  • Restart the app.

  • Cancel further alerts about exceeding that threshold. Ideally, the user should then delete the app from the document; continuing the app would risk further performance and stability issues.

Office provides a Telemetry Log that maintains a record of certain events (loading, opening, closing, and errors) of Office solutions running on the local computer, including resource usage issues in an app for Office. If you have the Telemetry Log set up, you can use Excel to open the Telemetry Log in the following default location on your local drive:

%Users%\[Current user]\AppData\Local\Microsoft\Office\15.0\Telemetry

For each event that the Telemetry Log tracks for an app, there is a date/time of the occurrence, event ID, severity, and short descriptive title for the event, the friendly name and unique ID of the app, and the application that logged the event. You can refresh the Telemetry Log to see the current tracked events. Table 1 lists a couple examples of mail apps, Who’s Who and LinkedIn, which was tracked to have their manifests loaded successfully in Outlook.

Table 1. Example events of mail apps tracked in the Telemetry Log

Date/Time

Event ID

Severity

Title

File

ID

Application

10/8/2012 5:57:10 PM

7

App manifest downloaded successfully

Who's Who

69cc567c-6737-4c49-88dd-123334943a22

Outlook

10/8/2012 5:57:01 PM

7

App manifest downloaded successfully

LinkedIn

333bf46d-7dad-4f2b-8cf4-c19ddc78b723

Outlook

Table 2 lists the events that the Telemetry Log tracks for apps for Office in general.

Event ID

Title

Severity

Description

7

App manifest downloaded successfully

The manifest of the app for Office was successfully loaded and read by the host application.

8

App manifest did not download

Critical

The host application was unable to load the manifest file for the app for Office from the SharePoint catalog, corporate catalog, or the Office Store.

9

App markup could not be parsed

Critical

The host application loaded the app for Office manifest, but could not read the HTML markup of the app.

10

App used too much CPU

Critical

The app for Office used more than 90% of the CPU resources over a finite period of time.

15

App disabled due to string search time-out

Mail apps search the subject line and message of an e-mail to determine whether they should be displayed by using a regular expression. The mail app listed in the File column was disabled by Outlook because it timed out repeatedly while trying to match a regular expression.

18

App closed successfully

The host application was able to close the app for Office successfully.

19

App encountered runtime error

Critical

The app for Office had a problem that caused it to fail. For more details, look at the Microsoft Office Alerts log using the Windows Event Viewer on the computer that encountered the error.

20

App failed to verify licensing

Critical

The licensing information for the app for Office could not be verified and may have expired. For more details, look at the Microsoft Office Alerts log using the Windows Event Viewer on the computer that encountered the error.

For more information on setting up the Telemetry Log on a Windows computer, see Deploying Telemetry Dashboard. For more information about the Telemetry Log for Office, see Troubleshooting Office files and custom solutions with the Office Telemetry Log

While the resources limits on CPU and memory usage, crash tolerance, UI responsiveness apply to apps for Office running only on the rich clients, optimizing the usage of these resources and battery should be a priority if you want your app to perform satisfactorily on all supporting clients and devices. Optimization is particularly important if your app carries out long-running operations or handles large data sets. The following list suggests some techniques to break up CPU-intensive or data-intensive operations into smaller chunks so that your app can avoid excessive resource consumption and the host application can remain responsive:

  • In a scenario where your app needs to read a large volume of data from an unbounded dataset, you can apply paging when reading the data from a table, or reduce the size of data in each shorter read operation, rather than attempting to complete the read in one single operation.

    For a JavaScript and jQuery code sample that shows breaking up a potentially long-running and CPU-intensive series of inputting and outputting operations on unbounded data, see How can I give control back (briefly) to the browser during intensive JavaScript processing?. This example uses the setTimeout method of the global object to limit the duration of input and output. It also handles the data in defined chunks instead of randomly unbounded data.

  • If your app uses a CPU-intensive algorithm to process a large volume of data, you can use web workers to perform the long-running task in the background while running a separate script in the foreground, such as displaying progress in the user interface. Web workers do not block user activities and allow the HTML page to remain responsive. For an example of web workers, see The Basics of Web Workers. See Web Workers for more information about the Internet Explorer Web Workers API.

  • If your app uses a CPU-intensive algorithm but you can divide the data input or output into smaller sets, consider creating a web service, passing the data to the web service to off-load the CPU, and wait for an asynchronous callback.

  • Ensure you test your app against the highest volume of data you expect, and restrict your app to process up to that limit.

Show:
© 2014 Microsoft