office365 - Neat ways to get environment (i.e. Office version)

Question

Unfortunately, some features of the office API do not behave exactly the same in all environments (example: formatting in Excel Online and Excel 2013). Additionally, some nice new features are not available in Excel 2013 but are available in Excel 2016 (Excel.js)

Of course, I could tell users they can only use my app with 2016, and simply not implement things that aren't fully supported in all environments.

I would prefer offering my app to users of Excel 2013 even if they don't have a way (or the inclination) to upgrade to 2016. And I would rather gracefully downgrade my feature list in less capable environments than limit the app's functionality as a whole)

It's easy enough to encapsulate all interaction with the document and run different code depending on the environment. That is, if I know what exact environment I'm in. does the current office.js offer a neat way to discover version and context(online/offline) of the host application? I couldn't find anything in office.context... etc.

There are some suggestions online about hacking into the whole .getContext chain, but these seem to be "undocumented", so I'm not quite happy with that.

Any suggestions?

Answer 1

Update Dec 5, 2016: We will soon be releasing an API to detect the platform info (partially in response to the fact that the _host_info URL paramater, which folks had unofficially relied on, needed to be recently removed for Office Online). We also have a temporary workaround in anticipation of the forthcoming official API. See "In Excel Online, OfficeJS API is not passing the host_Info_ parameter anymore to Excel Add-In" for information on the API and workaround.

I am keeping the old answer below, as it is still relevant for most light-up scenarios. Platform-detection should still be used sparingly, as querying API sets give you more fine-grained control, and ensures that your add-in "lights up" new features when they are added to a particular platform].

---

It sounds like you're describing a "light-up" scenario. For these sort of use cases, it isn't so much the actual version that you care about (do you really want to keep an internal list of all the minimum versions -- of Excel desktop, and soon Excel Online and iOS, and keep that updated?), but rather, you want to check the capability that something is present. And then offer a differentiated experience depending on whether the capability is there or not.

To that end, I would recommend a brand-new API that we just released alongside these APIs (and that is back-ported to all previous versions -- so as long as you're using the latest Office.js from the CDN, you should be good to go). That API offers you the ability to check, at runtime, whether a particular API set is supported. It looks like:

if (Office.context.requirements.isSetSupported('ExcelApi', 1.1)) {
    // Do something that is only available via the new APIs
}

Official documentation for it is forthcoming shortly, and our sample will soon start using it as well. Stay tuned...

The current set of newly-released Excel APIs is all under "ExcelApi" version 1.1. As we add new APIs, we'll add them to a 1.2 set, 1.3 set, and so on (and mark in the documentation and IntelliSense what set version each API is available in). Does that make sense?

---

For completeness sake, a few other things to note about Office.js versioning:

1) To ensure that you have the latest APIs, bug fixes, etc., you should always use the CDN location, which gets updated in-place as we roll out new features. That location is https://appsforoffice.microsoft.com/lib/1/hosted/office.js. https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js also works, with the "1" version being just an alias to "1.1" at the moment... but long-term, it's probably best to switch over to the "1" URL.

2) Corollary to the above: you should always use the latest CDN location even for older hosts. That way, you both get "light-up" for new features, and bug fixes (including for older host versions). Basically, you can always use the latest CDN, and rely on the dynamic loading of Office.js script to load the actual host-specific files you need.

3) You can use the new isSetSupported API for both the new API sets "ExcelApi" and "WordApi", and for existing sets (e.g., "MatrixBinding").

4) For APIs that are part of the "Office." namespace, you can also use "defensive programming" to do runtime checks for individual functions (e.g., check that Office.context.document.bindings && Office.context.document.bindings.addFromSelectionAsync) are supported. However, you can see that this can get quite verbose, so checking for a set should be much easier. Also, this will NOT work for APIs under the "Excel" or "Word" namespaces, so all the more reason to use the Office.context.requirements.isSetSupported API.

5) Finally: for apps that ONLY make sense to run if a given requirement set is present, you can specify the API set in the app's manifest. That being said, a manifest check is about specifying the absolute minimum essentials, without which the app simply won't run (or even show up as available in the insert dialog). A runtime check, meanwhile, lets you control how you want to react if a particular API is unsupported (offering the option of "lightup" features, or a downgraded experience). So, I would generally recommend using the lowest manifest-requirement that makes sense for your app, and then doing runtime checks to light up for new features.

Hope this helps,

~ Michael Zlatkovsky
   Developer on Office Extensibility team, MSFT