Simulate older API versions for testing - excel

I am developing an Excel add-in. My local version of Excel is running the latest so I have access to all of the most recent API calls. However, I want to be able to test the experience (and work around potential API holes) for a user that has a different version.
As an example, I am making use of the getRangeOrNullObject call which became available in v1.4 of the API. Is there any reasonable way to simulate using an older version? I want to be able to handle a bad range without making use of getRangeOrNullObject in a "real" environment.
I have tried pointing to a specific version, eg:
https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js
However that seems to load the most recent. Other versions (1.2, 1.3) are a 404.

From the Office Dev Center:
Specify Office hosts and API requirements
Your Office Add-in might depend on a specific Office host, a requirement set, an API member, or a version of the API in order to work as expected. For example, your add-in might:
Run in a single Office application (Word or Excel), or several applications.
Make use of JavaScript APIs that are only available in some versions of Office. For example, you might use the Excel JavaScript APIs in an add-in that runs in Excel 2016.
Run only in versions of Office that support API members that your add-in uses.
This article helps you understand which options you should choose to ensure that your add-in works as expected and reaches the broadest audience possible.
For a high-level view of where Office Add-ins are currently supported, see the Office Add-in host and platform availability page.
See full article at the source.
Related links:
Microsoft Docs : Usability testing for Office Add-ins
GitHib : NamedItem Object (JavaScript API for Excel)
GitHub : Excel JavaScript API requirement sets
Microsoft Docs : Specify Office hosts and API requirements

Related

OfficeJS API - Get version of the add-in installed in client machine

I am developing an add-in for Word, Excel and PowerPoint. I need to fetch the version of the add-in installed in client machine. I can see the version under 'Security Info' but I need to get it in my script at runtime.
Is there any OfficeJS API to fetch add-in version or get 'Security Info' programmatically ?
Have a look at this question. There isn't currently an API to get the version of the add-in from the add-in manifest.
If this solution described doesn't meet your needs, please head over to Microsoft 365 Developer Platform and post a request for the API team to consider. It will be helpful, if you provide more details on why getting the version information from the manifest is valuable for your use case.
The Office JavaScript API (OfficeJS) doesn't provide anything for that. Typically the version of Office add-ins is specified in the add-in manifest file where you can't access it from JS until it is hosted with a web app. If it is uploaded to the same place/server with your web app and you know the exact URL you may try to fetch the content and read the version from there. Otherwise, you have to define the version in the JS files or pass it as an URL parameter like Michael described.
If you find it inconvenient (as I do) you can post or vote for an existing feature request on Tech Community where they are considered when the Office dev team go through the planning process.

Office Scripts VS Office Lab

I am confused about Office Scripts and Office Lab.
Both can run javascript in Excel, but it seems the code can't be shared in them.
For Office Scripts, some code like
function main(workbook: ExcelScript.Workbook) {
// Set fill color to FFC000 for range Sheet1!A2:C2
let selectedSheet = workbook.getActiveWorksheet();
selectedSheet.getRange("A2:C2").getFormat().getFill().setColor("FFC000");
}
For Script lab, the code is
await Excel.run(async (context) => {
let sheet = context.workbook.worksheets.getActiveWorksheet();
sheet.tables.add("B2:E5", true);
await context.sync();
});
The workbook are different in ExcelScript.Workbook and context.workbook
They’re extremely different but there is an element of perceived cross over.
The script lab is in place to help you with the process of building Office JS add-ins but it's not the complete solution. You need to build the add-ins using the SDK's Microsoft provide through an IDE like VS or VS code. It's the cross platform mechanism for building add-ins that work on Excel for web, Windows and Apple platforms.
Office Scripts provides a mechanism for writing Typescript functions that are then able to be executed from PowerAutomate flows.
Also, with Office JS, you can create a fully functioning action pane with HTML/CSS, etc. that your user can interact with. The current extent that Office Scripts provide is a button with script behind. It's really more of an interface mechanism that the user wouldn't typically interact with. They're really powerful when you consider you can mix and match the inputs and outputs with other actions in PowerAutomate.
This is a direct quote from the documentation.
Office Add-ins are cross-platform. They work across Windows desktop,
Mac, iOS, and web platforms and provide the same experience on each.
Any exception to this is noted in the documentation of the individual
API.
Office Scripts are currently only supported by for Excel on the web.
All recording, editing, and script management is done on the web
platform.
While the Office JavaScript APIs for Office Add-ins and the Office
Scripts APIs share some functionality, they are different platforms.
The Office Scripts APIs are an optimized, synchronous subset of the
Excel JavaScript API model. The major difference is usage of the
load/sync paradigm with add-ins. Additionally, add-ins offer APIs for
events and a broader set of functionality outside of Excel, known as
the Common APIs.
An add-in compared to a flow function are very different from a usage perspective and so is the development process. Also, you host your add-in on a web server somewhere when you build it using Office JS whereas with Office Scripts, it's all done for you. The scripts are stored in your OneDrive and the platform has the application model for execution, you don't reference and use that SDK in a self contained project like you do for Office JS.
Some resources to reference ...
https://learn.microsoft.com/en-us/office/dev/scripts/resources/vba-differences
https://learn.microsoft.com/en-us/office/dev/add-ins/overview/explore-with-script-lab
There are two different APIs: Office.js and Office Scripts. Office.js has APIs available on platforms other than Excel (e.g. Word, OneNote, etc.). Office Scripts is currently only available for Excel.
ScriptLab is an add-in meant for exploring the Office.js APIs. While you can try to use it for automation, it's not meant to be a development environment. You can however experiment with the API, create custom functions, etc. You can later create more sophisticated add-ins using an Office Add-in creator like Yeoman generator for Office. Add-ins would then be deployed to a server where they could be utilized on any platform supported (PC, Mac, Web, etc.)
Office.js is more suited towards traditional developers. To develop add-ins, in addition to TypeScript, you may also need knowledge of HTML / CSS. In terms of JavaScript / TypeScript, you also need to know about promises or asynchronous concepts
Office Scripts is a simplified API. It is actually built on top of Office.js. It does not require knowledge of HTML / CSS, promises, asynchronous concepts, etc. It also does not require deployment to a web server. Because it's simplified, the APIs actually end up being different. But overall the APIs aren't too different. If you're looking to do relatively simple automation and don't want to deal with the overhead of developing add-ins, Office Scripts are a good choice. It's also a good choice if you want to do simple scripting to integrate with PowerAutomate.

How do I distribute excel office add-in(w/ office.js) in privately?

Q1. Are there any method to distribute excel office add-in(w/ office.js) in privately?
(Will office.js add-in also be distributed like VSTO's .exe OR .xla/.xlam macro files with password?)
Q2. If I run office add-in server(node.js) on my on-premise server, What will have to be distributed to the end-users?
(I want to hide the core source logic unlike VBA macro.)
I am now developing an excel office add-in. But there seems to be some limitation to deploy to the end-users in my company.(We are now testing environment for pilot, and using office 365 but it is restricted by IT's policy)
When I refer to the official documentation below, the docs says that the way to deploy add-in in privately are Microsoft 365 admin center OR SharePoint catalog.(AppSource is publicly for everyone.)
refer. https://learn.microsoft.com/en-us/office/dev/add-ins/publish/publish
However, it seems that it have to use Microsoft's services or components like SharePoint or admin center. I don't want to use these items because I want to flexibly cope with various environments.
I have also read the article as below.
refer. How to distribute private office add-ins?
But the reply thread seems that the writer couldn't get the appropriate answer what I also want to know.
I want to know the other ways to distribute excel office add-in(w/ office.js) without unveiling my core source logic and what is the minimum materials I have to provide to the end-users(i.g. manifest or something).
Typically, as you have already know, you need to host the add-in's source code on the web server anywhere. The manifest file just refers to the place where the sources are stored. And the single file which should be provided to be able to side-load add-ins locally is the manifest file. Everything else is hosted under your control.
Due to the nature of the web technology you can't hide the source code from users. The add-in acts like a regular web page. The best what you could do is to obfuscate your code.

In an Office Add-in developed using Office.js for Office Online, where is the process hosting the office application?

I have read the entire VSTO documentation to start with and skimmed over most of the Office Add-ins (office.js) documentation on MSDN but not found the answer to my question.
Could you please provide me with an answer and also, if possible, please point me to the page on MSDN that answers my question?
Question
In a scenario where the client computer does not have Microsoft Office installed, and is using a browser to access Office Online, and he loads an Office add-in written using Office.js, in such a scenario, where is the computer that hosts the COM objects and the Office process they reside in?
Here is my understanding of the elements involved in using Office.js add-ins:
There's the Open XML document that has the data. This is just dead-meat. It had to be loaded into a process.
Earlier, that process used to be the unmanaged WINWORD.EXE (or EXCEL.EXE or POWERPNT.EXE or another office application) process.
Now, with office.js, when using Office Online, i.e. the Web client, the unmanaged Office process still has to be allocated in memory in some computer? Basically, that's the core of my question.
My guess is
that it has to, and that the process may be run remotely on a
server. The document itself may be hosted remotely, which isn't a
big deal but the process, too, is required and in the case of Office
Online, the unmanaged office process is run on a remote computer. It
is this assumption I want to confirm or invalidate.
There's the client UI. This used to be a mesh of unmanaged C++ code within the office application and managed UI created by .NET using VSTO and Windows Forms or WPF. Now, with Office.js, this is done using HTML/CSS/JavaScript and can be loaded by any kind of a client (desktop/Web).
The process hosting the document and providing the underlying Document, Bookmark, Range et al objects. My question is -- for Office Online clients that do not have MS Office installed on the client computer, where is this process now if they use Office Add-ins written using office.js?
Am I wrong in assuming that the JavaScript API for Office Add-ins merely calls into the existing Office COM infrastructure we already know about? If I am right, then where is the machine that hosts the Winword.exe (or whichever Office application) process?
To answer the question of where the code is executed: There are no "COM" objects per se (the new wave of Office.js APIs is not based on the VBA COM objects, at least not directly). But there is indeed a backing server that has the document open and in-memory. In the case of Excel, the Excel Online front-end is a fairly "thin" layer, and almost all operations are executed by the supporting server. That server doesn't run EXCEL.exe directly, but it has a web service that is kinda-sorta-like Excel (and that shares a lot of the same underlying C++ code), which runs in a "headless" mode, one instance per document. In the case of Word, on the other hand, Word Online has a lot more business logic that it can execute locally, and so a lot of the operations are executed on the browser and sync back up to the server at idle time (much like end-user operations), but there is still a backing server that serves the appropriate data to the Word Online front-end, and that processes some operations (e.g., range.getOoxml(), or image.getImage()).
Hope this helps.
Office Web Add-ins (office-js) are web apps that leverage a specific library (office-js) to facilitate communication between the add-in and the host application.
As these add-ins are simply web apps, they work across the various Office platforms (Windows, Web, Mac, iOS). For browser based Office editions, add-ins are surfaced in an iframe. For native editions they are hosted in an embedded browser (IE11, Webkit, etc. depending on the platform).
Add-ins consist of two components, an XML manifest and the web app. The manifest can be loaded from a number of locations from directly side-loading, to a network share, to the Office Store. The web app is hosted wherever you would normally host your web apps (I recommend Azure but then I'm a bit biased). They are never hosted by Microsoft directly.

Office-JS: Excel Host API no longer available under Excel 2016 MSO

I'm currently running Windows 10 with Microsoft Excel 2016 MSO (16.04266.1001) 64-bit. I'm under the impression that that is the version installed via MSI.
Over the course of the last few months I've implemented a React-based Excel add-in using the Excel Host APIs. Per the Excel JavaScript API requirement sets document available at the Office Dev Center, that build appears to contain the "ExcelApi 1.1, WordApi 1.1, and common API" requirement sets.
As of yesterday, I am no longer able to access the Excel host APIs through JavaScript or through the F12 developer tools (window.Excel === undefined). It appears that all the functionality under that had previously existed under that namespace has become unavailable.
It appears that (among other scripts), the office.js script loaded from the CDN now requests and embeds Excel-15.02.js for the add-in.
I do not know the version of Excel-*.js that was being embedded before yesterday, but after perusing the contents of both Excel-15.02.js, Excel-winrt-16.00.js and other versions available on the CDN, I suspect that it was a later version than 15.02.
For the record, both of the following runtime checks return false - I say both, because "API" is capitalized inconsistently in the documentation available at dev.office.com.
Office.context.requirements.isSetSupported("ExcelApi", 1.1); // false
Office.context.requirements.isSetSupported("ExcelAPI", 1.1); // false
Please advise; best regards.
I am investigating the issue. A few questions:
You mention that the files being loaded include Excel-15*.js files. How are you seeing this -- is it through Fiddler, or through a debugger? If you can send a Fiddler trace, that would be really useful (a Fiddler trace may contain some sensitive info, so you may want to scrub it -- and feel free to send it to me directly rather than posting it here online)
If you browse to https://appsforoffice.microsoft.com/lib/1/hosted/office.js in a browser, what is the version number that you see at the top of the file?
If you are comfortable deleting your IE cache: could you see if the issue continues to repro even after you've cleared the cache?
Feel free to reply here via comments, or as updates to your questions, or to email me directly. My email is my full name (separated by a dot between first and last) at microsoft.com.
I will be updating this answer as I have more info.

Resources