|
| 1 | +--- |
| 2 | +title: Check for API availability at runtime |
| 3 | +description: Learn how to verify at runtime that the Office application supports your add-in's API calls. |
| 4 | +ms.topic: best-practice |
| 5 | +ms.date: 02/12/2025 |
| 6 | +ms.localizationpriority: medium |
| 7 | +--- |
| 8 | + |
| 9 | +# Check for API availability at runtime |
| 10 | + |
| 11 | +If your add-in uses a specific extensibility feature for some of its functionality, but has other useful functionality that doesn't require the extensibility feature, you should design the add-in so that it's installable on platform and Office version combinations that don't support the extensibility feature. It can provide a valuable, albeit diminished, experience on those combinations. |
| 12 | + |
| 13 | +When the difference in the two experiences consists entirely of differences in the Office JavaScript Library APIs that are called, and not in any features that are configured in the manifest, then you test at runtime to discover whether the user's Office client supports an [API requirement set](office-versions-and-requirement-sets.md). You can also [test at runtime whether APIs that aren't in a set are supported](#check-for-setless-api-support). |
| 14 | + |
| 15 | +> [!NOTE] |
| 16 | +> To provide alternate experiences with features that require manifest configuration, follow the guidance in [Specify Office hosts and API requirements with the unified manifest](specify-office-hosts-and-api-requirements-unified.md) or [Specify Office applications and API requirements with the add-in only manifest](specify-office-hosts-and-api-requirements.md). |
| 17 | +
|
| 18 | +## Check for requirement set support |
| 19 | + |
| 20 | +The [isSetSupported](/javascript/api/office/office.requirementsetsupport#office-office-requirementsetsupport-issetsupported-member(1)) method is used to check for requirement set support. Pass the requirement set's name and the minimum version as parameters. If the requirement set is supported, `isSetSupported` returns `true`. The following code shows an example. |
| 21 | + |
| 22 | +```js |
| 23 | +if (Office.context.requirements.isSetSupported("WordApi", "1.2")) { |
| 24 | + // Code that uses API members from the WordApi 1.2 requirement set. |
| 25 | +} else { |
| 26 | + // Provide diminished experience here. |
| 27 | + // For example, run alternate code when the user's Word is |
| 28 | + // volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2). |
| 29 | +} |
| 30 | +``` |
| 31 | + |
| 32 | +About this code, note: |
| 33 | + |
| 34 | +- The first parameter is required. It's a string that represents the name of the requirement set. For more information about available requirement sets, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets). |
| 35 | +- The second parameter is optional. It's a string that specifies the minimum requirement set version that the Office application must support in order for the code within the `if` statement to run (for example, "1.9"). If not used, version "1.1" is assumed. |
| 36 | + |
| 37 | +> [!WARNING] |
| 38 | +> When calling the `isSetSupported` method, the value of the second parameter (if specified) should be a string, not a number. The JavaScript parser can't differentiate between numeric values such as 1.1 and 1.10, whereas it can for string values such as "1.1" and "1.10". |
| 39 | +
|
| 40 | +The following table shows the requirement set names for the application-specific API models. |
| 41 | + |
| 42 | +|Office application|RequirementSetName| |
| 43 | +|---|---| |
| 44 | +|Excel|ExcelApi| |
| 45 | +|OneNote|OneNoteApi| |
| 46 | +|Outlook|Mailbox| |
| 47 | +|PowerPoint|PowerPointApi| |
| 48 | +|Word|WordApi| |
| 49 | + |
| 50 | +The following is an example of using the method with one of the Common API model requirement sets. |
| 51 | + |
| 52 | +```js |
| 53 | +if (Office.context.requirements.isSetSupported('CustomXmlParts')) { |
| 54 | + // Run code that uses API members from the CustomXmlParts requirement set. |
| 55 | +} else { |
| 56 | + // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set. |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +> [!NOTE] |
| 61 | +> The `isSetSupported` method and the requirement sets for these applications are available in the latest Office.js file on the CDN. If you don't use Office.js from the CDN, your add-in might generate exceptions if you are using an old version of the library in which `isSetSupported` is undefined. For more information, see [Use the latest Office JavaScript API library](specify-office-hosts-and-api-requirements-unified.md#use-the-latest-office-javascript-api-library). |
| 62 | +
|
| 63 | +## Check for setless API support |
| 64 | + |
| 65 | +When your add-in depends on a method that isn't part of a requirement set, called a setless API, use a runtime check to determine whether the method is supported by the Office application, as shown in the following code example. For a complete list of methods that don't belong to a requirement set, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets#methods-that-arent-part-of-a-requirement-set). |
| 66 | + |
| 67 | +> [!NOTE] |
| 68 | +> We recommend that you limit the use of this type of runtime check in your add-in's code. |
| 69 | +
|
| 70 | +The following code example checks whether the Office application supports `document.setSelectedDataAsync`. |
| 71 | + |
| 72 | +```js |
| 73 | +if (Office.context.document.setSelectedDataAsync) { |
| 74 | + // Run code that uses `document.setSelectedDataAsync`. |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +## See also |
| 79 | +- [Office requirement sets availability](office-versions-and-requirement-sets.md#office-requirement-sets-availability) |
| 80 | +- [Specify Office hosts and API requirements with the unified manifest](specify-office-hosts-and-api-requirements-unified.md) |
| 81 | +- [Specify Office hosts and API requirements with the add-in only manifest](specify-office-hosts-and-api-requirements.md) |
0 commit comments