Debugging Office Add-ins on iOS (iPad)
In the last article I talked about the development experience of the Office Add-in in one day. The result of that day was the add-on XLTools Calendar, which is working and ready for publication in the Office Store. Then I expected that the Excel add- in , developed and tested under the desktop version, will work in Excel for iPad and for the Web. The API is the same everywhere, therefore, the code that uses this API should work the same way, especially since I already had a number of Add-ins, which I earned on all platforms without additional changes. This did not happen with the calendar, and I recognized the bitterness of the “failure” of publications in the Office Store . In this article I will explain why the XLTools.net Calendar add-in did not pass the test the first time, and how to avoid it.
At the end of last year, Seller Dashboard had the opportunity to mark Office add-ins as available on iOS . This option allows you to publish Add-ins for Excel, Word and Power Point in the mobile version of the Office Store for iPad. At the time of this writing, it contained about 10 add-ins. I wondered if we could even get there, so by publishing the XLTools.net Calendar, I turned on this option.
')
As a result of checking the calendar with the Office Store team, I was refused a publication. The reason for the refusal was errors in the work of the add-in in the Web and iPad versions of Excel. With the web figured out quickly, there is nothing complicated. For debugging, you can use the Developer Tools in any of the browsers. But with the iPad there were difficulties. Initially, I did not even imagine how to run an Add-in on an iPad, bypassing the Office Store. Not to mention debugging.
Partly helped by MSDN, found a couple of useful articles on this topic:
The process of loading the Add-in on iPad (Sideloading) is described in detail in the first article. To download you need iTunes, installed on your PC, and a cord to connect your iPad to a PC. To make Excel “see” and be able to run the add-in, you need to load the manifest file for Excel for iPad. For this:
After that, the add-in will be available from the Excel interface.
Particular attention should be paid to the fact that to run on the iPad, the add -in website must be accessible via HTTPS . With this, I suffered for a long time, because initially indicated in the manifest file a link to the site deployed on the work computer without an SSL certificate installed. As a result, the add-in was launched, but gave an error.
A self-signed certificate will also not work, you need a trusted one or, as the error text says, a “valid” certificate.
Having investigated the issue of launching Add-ins with HTTPS, I found two working options:
For debugging purposes, the second option is more interesting, since allows you to debug the server add-on code (if any).
ngrok is a console utility that works like a tunnel for a local Internet site. Once launched, ngrok assigns a dynamic domain name to the site. All requests to this domain are redirected by the ngrok service to the local site - thereby emulating the work of a real add-on published on the Internet, and the possibility of local debugging remains. An added bonus is that the dynamic domain supports HTTP and HTTPS connections. This is what we need to run the Add-in in Excel.
To work ngrok site must be deployed on the local IIS service. It is also possible to “incite” ngrok on IIS Express, but it is a bit more complicated. Read more about IIS Express here .
Suppose we deployed a site on a local IIS server, port 8081. To create a tunnel through ngrok, you need:
Ngrok gives us a set of URLs, among which we are interested in the one that starts with https:
We transfer the resulting URL to the manifest file. All links to the add-in site need to be replaced with a new address generated by ngrok:
After that, the manifest file must be copied to the iPad, as described above. And voila - add-in earned:
The process of debugging Add-ins for iPad and Mac is described in the second of the above articles. The only subtlety that the author of the article did not take into account on MSDN is HTTPS. We will analyze in more detail.
Weinre is a web page debugger, similar to the Developer Tools, but created for remote debugging of web pages running on mobile devices. Written on NodeJS.
To run Weinre you need:
An MSDN article tells us that for remote debugging you need to add the following script to the add-in web page:
If we do that, nothing will work. As we remember, the add-in works on HTTPS. This means that all resources on the page must also be loaded via HTTPS. If you add an HTTP script to the page code, it will be blocked by the browser, and Weinre will not work. In this situation, ngrok comes to the rescue again. Open the new console (the old consoles, where we have already started ngrok and weinre, cannot be closed) and run the ngrok http 8080 command to create another HTTPS tunnel for Weinre.
After receiving the url from ngrok, we include the Weinre script into the add-in:
where ngrok https address is the url that ngrok assigned to us for the Weinre service.
Preparation completed, you can proceed to debugging. To do this, run the add-on on your mobile device and go to the Weinre page, which displays the list of connected devices (Targets): http: // localhost: 8080 / client / # anonymous
It is worth noting that when adding JavaScript to the text of the add-in page, problems may arise with the cache, i.e. Excel on the iPad will load the same version of the page that it loaded earlier (without added JavaScript for Weinre). In this case, adding a get- parameter "version" to the url in the manifest file helps : home.html? V = 1 .
There is also an inaccuracy in the description of the debugging process on MSDN. They write that for debugging you need to use "your favorite browser's F12 developer tools", although it is more correct to say "your favorite browser". Developer Tools will not help here, because The debug interface is provided by Weinre itself. In function, it is similar to the Developer Tools for Chrome and provides exactly the same features, with the exception of breakpoints and step-by-step debugging of JavaScript, which is a strong limitation.
For example, go to the Elements section and change the text of the element and its color. All changes are automatically displayed in the Add-in on iPad:
You can debug JavaScript only through the Weinre console. The console allows you to access global variables and run the commands we need. This is how I debugged the calendar, because in my case, the problems were in javascript code.
Currently, debugging Office Add-ins for mobile devices is far from the experience that Visual Studio gives us. However, sometimes you can't do without it, and the fact that such a debugging option is, in principle, is better than nothing. Despite the difficulties and drawbacks of such a debugging method, I managed to correct errors in the XLTools.net Calendar add-in, after which it was successfully tested and published in the Office Store — download, use !
Write in the comments about your debugging experience with Office Add-ins. What problems were encountered? How did you manage to solve them? Ask questions, I will try to answer them promptly.
Peter Lyapin - Technical Director of Wave Point Ltd.
More than 10 years of experience in implementing projects for automating business processes. He worked with many Russian and foreign companies. Founder of the XLTools.net project. Since 2013, together with the XLTools project team, has been creating and promoting add-ons for Office 365 and is the author of more than 7 solutions published in the Office Store.
The first publication in the Office Store "lumpy"
At the end of last year, Seller Dashboard had the opportunity to mark Office add-ins as available on iOS . This option allows you to publish Add-ins for Excel, Word and Power Point in the mobile version of the Office Store for iPad. At the time of this writing, it contained about 10 add-ins. I wondered if we could even get there, so by publishing the XLTools.net Calendar, I turned on this option.
')
To include a previously published Office add-in in the mobile directory, it must be republished, i.e. release an updated version and activate this option in it.
For Office add-ons available on iOS, there is one significant limitation - they cannot be paid.
As a result of checking the calendar with the Office Store team, I was refused a publication. The reason for the refusal was errors in the work of the add-in in the Web and iPad versions of Excel. With the web figured out quickly, there is nothing complicated. For debugging, you can use the Developer Tools in any of the browsers. But with the iPad there were difficulties. Initially, I did not even imagine how to run an Add-in on an iPad, bypassing the Office Store. Not to mention debugging.
Partly helped by MSDN, found a couple of useful articles on this topic:
Download Office Add-ins to iPad for debugging
The process of loading the Add-in on iPad (Sideloading) is described in detail in the first article. To download you need iTunes, installed on your PC, and a cord to connect your iPad to a PC. To make Excel “see” and be able to run the add-in, you need to load the manifest file for Excel for iPad. For this:
- Connect iPad to computer with iTunes installed;
- Launch iTunes;
- Go to the iPad control section;
- Go to the Apps section;
- Scroll down to the File Sharing section;
- Find and select Excel;
- Drag the manifest file from Explorer into the Excel Documents window.
After that, the add-in will be available from the Excel interface.
Particular attention should be paid to the fact that to run on the iPad, the add -in website must be accessible via HTTPS . With this, I suffered for a long time, because initially indicated in the manifest file a link to the site deployed on the work computer without an SSL certificate installed. As a result, the add-in was launched, but gave an error.
A self-signed certificate will also not work, you need a trusted one or, as the error text says, a “valid” certificate.
Having investigated the issue of launching Add-ins with HTTPS, I found two working options:
- Pre-posting on the HTTPS support test site. This can be either your own site with a trusted SSL certificate, or an Azure site that supports HTTPS by default, if you use yoursite .azurewebsites.net subdomain;
- Using the ngrok program, which allows you to make a local site accessible "from the outside" via HTTPS.
For debugging purposes, the second option is more interesting, since allows you to debug the server add-on code (if any).
Run Office Add-in via ngrok
ngrok is a console utility that works like a tunnel for a local Internet site. Once launched, ngrok assigns a dynamic domain name to the site. All requests to this domain are redirected by the ngrok service to the local site - thereby emulating the work of a real add-on published on the Internet, and the possibility of local debugging remains. An added bonus is that the dynamic domain supports HTTP and HTTPS connections. This is what we need to run the Add-in in Excel.
To work ngrok site must be deployed on the local IIS service. It is also possible to “incite” ngrok on IIS Express, but it is a bit more complicated. Read more about IIS Express here .
Suppose we deployed a site on a local IIS server, port 8081. To create a tunnel through ngrok, you need:
- Download the archive from ngrok and unzip it to a folder on your local computer;
- Go to the console and run the command: ngrok http 8081.
Ngrok gives us a set of URLs, among which we are interested in the one that starts with https:
We transfer the resulting URL to the manifest file. All links to the add-in site need to be replaced with a new address generated by ngrok:
After that, the manifest file must be copied to the iPad, as described above. And voila - add-in earned:
Debugging Office Add-in with Weinre
The process of debugging Add-ins for iPad and Mac is described in the second of the above articles. The only subtlety that the author of the article did not take into account on MSDN is HTTPS. We will analyze in more detail.
Weinre is a web page debugger, similar to the Developer Tools, but created for remote debugging of web pages running on mobile devices. Written on NodeJS.
To run Weinre you need:
- Install the latest version of NodeJS from https://nodejs.org/ ;
- Install Weinre by running the npm -g install weinre command in the console;
- Run weinre with weinre --httpPort 8080 --boundHost localhost ;
- Test Weinre by going to the localhost : 8080 home page.
An MSDN article tells us that for remote debugging you need to add the following script to the add-in web page:
<script src="http://<ipaddr>:8080/target/target-script-min.js#anonymous"></script> If we do that, nothing will work. As we remember, the add-in works on HTTPS. This means that all resources on the page must also be loaded via HTTPS. If you add an HTTP script to the page code, it will be blocked by the browser, and Weinre will not work. In this situation, ngrok comes to the rescue again. Open the new console (the old consoles, where we have already started ngrok and weinre, cannot be closed) and run the ngrok http 8080 command to create another HTTPS tunnel for Weinre.
After receiving the url from ngrok, we include the Weinre script into the add-in:
<script src="<ngrok https address>/target/target-script-min.js#anonymous"></script> where ngrok https address is the url that ngrok assigned to us for the Weinre service.
Preparation completed, you can proceed to debugging. To do this, run the add-on on your mobile device and go to the Weinre page, which displays the list of connected devices (Targets): http: // localhost: 8080 / client / # anonymous
It is worth noting that when adding JavaScript to the text of the add-in page, problems may arise with the cache, i.e. Excel on the iPad will load the same version of the page that it loaded earlier (without added JavaScript for Weinre). In this case, adding a get- parameter "version" to the url in the manifest file helps : home.html? V = 1 .
Debugging Features with Weinre
There is also an inaccuracy in the description of the debugging process on MSDN. They write that for debugging you need to use "your favorite browser's F12 developer tools", although it is more correct to say "your favorite browser". Developer Tools will not help here, because The debug interface is provided by Weinre itself. In function, it is similar to the Developer Tools for Chrome and provides exactly the same features, with the exception of breakpoints and step-by-step debugging of JavaScript, which is a strong limitation.
For example, go to the Elements section and change the text of the element and its color. All changes are automatically displayed in the Add-in on iPad:
You can debug JavaScript only through the Weinre console. The console allows you to access global variables and run the commands we need. This is how I debugged the calendar, because in my case, the problems were in javascript code.
findings
Currently, debugging Office Add-ins for mobile devices is far from the experience that Visual Studio gives us. However, sometimes you can't do without it, and the fact that such a debugging option is, in principle, is better than nothing. Despite the difficulties and drawbacks of such a debugging method, I managed to correct errors in the XLTools.net Calendar add-in, after which it was successfully tested and published in the Office Store — download, use !
Write in the comments about your debugging experience with Office Add-ins. What problems were encountered? How did you manage to solve them? Ask questions, I will try to answer them promptly.
about the author
Peter Lyapin - Technical Director of Wave Point Ltd.
More than 10 years of experience in implementing projects for automating business processes. He worked with many Russian and foreign companies. Founder of the XLTools.net project. Since 2013, together with the XLTools project team, has been creating and promoting add-ons for Office 365 and is the author of more than 7 solutions published in the Office Store.
Source: https://habr.com/ru/post/280898/
All Articles