Office Development – Word Add-in in Visual Studio ‘in action’

Yesterday in my blogpost I showed you the instructions to perform to create your first Word Add-in not by command line tools like I showed earlier, but by using Visual Studio 2017. So here it is:

Boot up your Visual Studio IDE and select File, new Project. In the New Project Dialog select on the left hand of the dialog the tree item Add-ins under the Office/SharePoint node. On the right hand you get options to build Add-ins for Excel, Word, Outlook, PowerPoint and SharePoint.

They still call it Web Add-in, if you ask me this name is a bit outdated. I believe the Add-ins are called just Office Add-ins (with the capital A). There was a time these things were called “Apps for Office”. The name used today on the http://dev.office.com website is:

Where were we? …. Oh, yes … Creating a new project. Name your new project any name you would like to give it, I opted for MyFirstWordAddin. Change the folder if you want to store it somewhere else other than the default project output path and click OK to start creating your project. If all goes well you’ll see the following ‘progress’ bar appearing on your screen.

It takes a couple of minutes to finish, but when it does it will open a code window like this:

And another tab was created to show you some helpful links to continue:

Now it is time to hit F5, the “Visual Studio Compile-Run-Debug Experience”. As we have seen ancient times ago the Office Dev team really tried to hide all the difficult stuff for you and it will create for you the security context to be able to actually run the Word Add-in without going through the hassle I described in other posts creating the Add-in using the command line tools like Yeomen.

The only dialog might get to see in between is this one:

A one time only trust entry for your self-signed Localhost certificate. You’ll notice if you create a second project this dialog won’t show again as you already trusted it for your first project. Click Yes otherwise your Add-in won’t be trusted to run. It will create the security context and an instance of Word is created and installed the just created Add-in.

On the top right hand in the Ribbon in the Home Tab a button appears in the Commands Group with some easy instructions. You’ve seen as similar button and instructions on the command line Add-in we created a while ago.

Click the button to have the Task pane appearing on the right hand. The sample Task pane wants you to select a couple of words in the document and if you press the Highlight button it will calculate the word with the most characters and highlights the word.

That is all there is to it … no fancy pansy difficult stuff to get around creating certificates and trusting the certificates. It is all done for you by the Visual Studio tooling. Impressive!

Beware however, you are not ready for production – just like the command line Add-in tools, the certificate is self signed, you are not running the ‘ web app’ in a shared (public) location to be able to access from anywhere and anytime. It is still ‘demo-ware’. Hopefully over time we will reach the golden moment of creating ‘production-ware’ Smile

To be continued …

August 26, 2017

Office Development – Word Add-in – Using Visual Studio

A while ago, not too long, I showed you how to start developing your Word Add-in from scratch using nothing but command line tools. Check my blog archives for the last couple of weeks if you missed that. Today we are looking at the same process but now using Visual Studio.

Where to begin? According to the page: https://dev.office.com/getting-started/addins going through the process of steps you select Word as Add-in host, and Visual Studio as tools to build your Add-in will finally show you the following screen:

It is already hopelessly outdated, mentioning to install the Office Developer Tools for Visual Studio 2013 or 2015 while Visual Studio 2017 has been around for quite some time.

The process however is still unchanged for the most part, I will show it in practice in a later blog, but if you follow the three steps you are basically already there, where without Visual Studio and just using the command line tools we had to go through a large series of requirements and certificate fixes to make that work.

Apparently Visual Studio takes a lot of this out of your hands and is doing all that for you. Not completely fair, because with Visual Studio you also need to go through the installation process. I want to find out what this all is and put that in a blog post as well

To be continued …

August 13, 2017

Office Development – Installing Script Lab

Yesterday in my blog a short introduction to Script Lab, the Microsoft Garage project to work in some sort of a playground to develop your JavaScript for Office scripts so you can test-drive your code that you plan to use in your Add-in.

Today I will go over the installation process of Script Lab. Step by step I’ll follow the instructions and see what this looks like. How hard can it be ‘ey?

To start installing navigate to https://aka.ms/getscriptlab. It looks like this:

Click the Add button to arrive at the guided installation page:

To stay in the mood, we select Word again. I’ll will be using other clients like Excel or PowerPoint soon, but to be consistent I’ll select Word again. This will provide you with a comparable environment and maybe you get used to it. Now, to open in Word click the “Open in Word” option. This will ‘warn’ you that you are about to switch applications:

As this is the plan, you want to move into Word instead of staying in Microsoft Edge. Select ‘Yes’ to go on. This will launch Microsoft Word 2016 (assuming you have Office 2016 installed):

A document is opened, but not without warning. Because you open the document from the dark and dangerous Internet you are provided with a warning and start in the Protected View of Office:

In this case we tend to trust Microsoft in this we continue our journey by pressing “Enable Editing” but now we run into a second warning because the document also contained a Task pane that wants to run the Script Lab Add-in.

Again to make you feel safe, you don’t want any add-in to kick in without your confirmation, you get the option to “Trust this add-in” or “See Details”.

If you click “See Details” they bring you back to base. The installer page is provided where you can read information about the add-in. I guess you already did that, otherwise you wouldn’t get this far in the installation process (unless you just trusted my simple introduction and went ahead ). For now, not all that interesting, so we close this and leave it for what it is.

We go ahead, and decide to trust this add-in. This will bring us the Script Lab tab:

Showing you a balloon with the text “Code, Run and share your Add-in snippets directly from Office” and a “Got It” button to confirm:

Click the Script Lab and you’ll see a ribbon appear with the options:

Code, Run, Tutorial, Help, Reference Docs and Ask the Community

The most obvious thing to do would probably be to go through the Tutorial, at least that was what I picked as a starting point. The interesting thing is however that the Tutorial brings you to an Excel environment to explain you what you can do with the Add-in:

You basically go through all the same steps again, but ending up in Excel showing you all the same options. Open a script-lab-tutorial.xlsx from script-lab.azureedge.net :

This is an Excel starter document with more information about the Add-in and guiding you through the options:

Again the little Protected View warning and the Enable Editing button.

It didn’t provide me with the Script Lab Add-in tab though, only the instructions that you also saw when running the Word installer, except now for Excel.

This wasn’t really what I was looking for, probably useful if I just started from Excel but I didn’t. I went through the GitHub issues and noticed that getting a Word Tutorial is still in planning. Some patience here.

For now, at least the Word Script Lab Add-in is installed and ready to use.

To be continued

August 9, 2017

Office Development – Fixing Trusted Authority – Word Client

Yesterday we’ve seen an issue installing a Word Add-in when the certificate used in the Add-in is not (yet) trusted:

To solve this, we need to add the server certificate as a trusted authority to the certificate store. In my post Office Development – Fixing Certificate Issue with OpenSSL Certificate I already showed you how to create the certificate. I even announced that I had to add the certificate to the trusted root certificates but, in the end, never did that – resulting in the issue above.

Clean up the installed Add-in

First, let’s clean up the installed Add-in to re-do the installation later on to see if it installs correctly after adding the certificate to the trusted root certificates.

Go back to the File/Options/Trust Center/Trust Center Settings … button and click it

Select the Trusted Catalog Address, click Remove and click OK to close the dialog. You’ll get a message that it will be effective when you close and open Word again.

Close Word to get it done.

Now start the certificate manager:
C:\Windows\System32\certmgr.msc

Select the Trusted Root Certification Authorities node, right click, All Tasks, Import …

Click Next to continue

Select the server certificate from the Add-in folder that you created while generating the certificate. Click Open and add the certificate.

Click Next

And … Finish to complete the certificate installation.

Install the Word Add-in again

Repeating the steps from the previous post, go to File/Options/Trust Center/Trust Center Settings … button and click it.

Add the network share again, don’t forget to check the checkbox. Close the dialogs and if you get this message below, close Word and start it again.

Now go to the Insert Tab and click My Add-ins.

Repeating the sequence that we did in our previous post, go to the Insert tab and click My Add-ins.

From the SHARED FOLDER tab select your Add-in again and click Add. Immediately you see the button at the Home Tab in the Commands Group.

And if you now click the button, the Add-in is now loaded without issues. No more warnings for security issues or incorrectly named certificates. It just runs.

So, what have we learned today

– Make sure your security is in place. Prepare your certificates with the correct names on the certificate and add it to the trusted root certificates.

(Note: most of these issues are originated by creating self signed certificates. When using commercially generated certificates most of these certificates already come from trusted root certificates)

– Cleaning (removing) installed Add-ins is not so trivial as you might expect. We had to remove the Catalog entry, closing Office and reopen Office clears the Add-in. It would be easier if the user interface provided an option to remove the Add-in in an easier manner.

(Note: removing the Add-in from Word Online is even worse. I asked the question on StackOverflow where it was confirmed that there is no easy remove option)

Recap

So far, we installed NodeJS, Git, Yeoman and created a simple Add-in. Next, we tried to install it on Word Online, fixed some security issues, installed it on the Word local client, fixed some more security issues and finally installed it on the local Word client again, this time without issues.

Not much interaction yet between the Add-in and Word but we’ll look at that later.

To be continued …

August 9, 2017

Office Development–Running Word Add-in on your local Word client

In my last post Office Development – Running Word Online Add-in I explained how to install your Add-in to use in Word Online. Today we will bring the same Add-in into your local Word client installation, Word 2016:

To do so you first need to start your ‘web server’ again by calling

npm start

from the root of your Add-in folder.

Now you have your ‘web server’ up and running and we need to make this visible for Word. Word is able to ‘see’ Add-ins that are exposed by manifest files in a shared network location or web URL. Today we will use the shared network location to expose the manifest file.

To create a shared network location, you simply create a dedicated folder on your machine:

In this case I just created an extra folder in the Add-in project called addinshare.

Don’t forget to copy the manifest file “my-first-addin-manifest.xml” to the just created folder!

Now create the network share by opening the Explorer. Go to “This PC” and select from the menu/ribbon “Manage”

This will open the Computer Management tool. Browse in the left tree to Computer Management\System Tools\Shared Folders\Shares, select it:

Select Action, New Share:

Go to the folder that you dedicated for your Add-in

Click Next to continue

If you like change the name of the share, and click Next

For now, add All Users have read-only access (you might want to change the access rights later on but for demo purposes pick the default) and click Finish.

Click Finish again to close the dialog and close the Management Tool.

Now back to Word, goto the Trust Center under File, Options, Tab Trust Center, Button “Trust Center Settings …”

On the left side select “Trusted Add-in Catalog” and in the Catalog URL enter the network share from your computer \\<computername>\<sharename> that you just created in the previous steps. Click Add catalog to push it in the list.

When added to the list, check the checkbox Show in Menu to make it available in Word.

Note: Before clicking “Add catalog” it would be a good thing to check in Explorer that your folder spelling of the shared folder is correct and is opened without issues.

Click OK twice to close the dialogs. You may see this as well:

If all went right you should be able to add your Add-in to Word. Close all instances of Word and restart Word.

Go to the Insert Tab, just like you did in Word Online from the previous post and click My Add-ins:

Clicking the My Add-ins button in the ribbon will give you the dialog below if you select the option SHARED FOLDER (notice that Word recognized the share and provided you with this menu option. If the share wasn’t recognized the option for SHARED FOLDER would not appear).

What is up? Didn’t we fix the certificate issue? We had it running in the browser, didn’t we?

Well, yes … but what I forgot was to add the certificate to the list of trusted authorities. For now we can go on, we know it is safe but we need to fix this later on (food for another blogpost ).

Click Yes to confirm, select the MyFirstAddin an click Add.

After closing the dialog by clicking Add a new Ribbon item is added to your Word Home Tab:

Kinda useless information, you are already on the HOME tab … nevertheless, click the “Show Taskpane” button to get started. For me this resulted in:

Sh*t happens so I refreshed the page, to see what happened:

A bit better, but still not right. This time we recognized the “not secure” warning. My own fault, it still needs the trusted authority fix. For now, click More information:

This opens up the option to Go on to the webpage (not recommended). We know it is ok in this case, if the source was unknown you should just back out and close the add-in. In this case we created it, know it is secure so we go on to the website, although it was not recommended. We like to be a little bit stubborn at times and there you have it, it worked:

Quite a journey again, still not flawless but cause by my own doing. We now have the Add-in running in both Word Online and in Word 2016 on your local machine.

In our next step, I’ll add the certificate to the trusted authorities to redo this without issues, hopefully…

To be continued

August 7, 2017

Office Development – Running Word Online Add-in

What we’ve seen so far is that we installed NodeJS, Git, Yeoman and fixed a security issue. All if this to create a basic ‘hello world’ Add-in. I must be honest and admit that running your first VBA add-in was a lot easier and running out of the box with just a few lines of code.

But let’s go on. We did run the Add-in as a website, but not as a real Add-in in the Word client. The instructions explain that the easiest thing to do would be to use Word Online. So here we go:

Open Word Online, go to the Insert Tab

Click the Office Add-ins button

On the top right select “Manage My Add-ins” to upload the Add-in manifest

Click Browse to find the Add-in manifest file

After uploading the manifest, you should see the Show Taskpane button appear in the Commands Group and if you click the button the Task pane appears showing you exactly what you’ve seen in our earlier blogpost:

And there you have it … your first Add-in running in the Word client. Congratulations.

I do have to admit that it didn’t work immediately … I had to upload the manifest more than once to get it to work. At first my icon didn’t appear, the group did but the Task pane didn’t load either after clicking the ‘no icon’-button. Trying again solved it (no clue to why the first attempt failed).

Obviously, the scenario we’ve seen so far won’t work ‘in production’. The Add-in website is currently still running on your local machine at a specific port (3000 in this case) and adding the Add-in using Word Online is not directly the most optimal way to get your Add-in up and running.

Our journey of research is apparently not ready yet. We need to overcome the ‘demo’ instructions and see if we can get it closer to a production ready system. I think my next step would be to find out how to run the Add-in in the Word client running on the desktop. Maybe the next step after that to run it on a Mac.

This all is still just running the Add-in, we haven’t seen any interaction with the documents. No fear, we will get there … I’m sure so keep with me and hang in here.

To be continued …

August 2, 2017

Office Development – Installing Git

In our previous step to build our first Word Add-in with JavaScript for Office we installed Nodejs. Today we continue with installing Git. Over time there will not be a need to install these tools again, by then you will be a professional web developer living in the world of these tools and probably have these installed already before jumping into another project.

For now I assume you didn’t have the tools installed, but you can check on the command line with the command:

git –version

If you already installed Git you probably see something like this:

You can find the Git installer just by GoogleBinging for “Git” and this will lead you to:

https://git-scm.com

Now, on the right you see a nice downloader button that selects your installer based on the machine that you are on. Click this, and hit Run (usually you wouldn’t be so dumb and save the downloader first on your machine in order to have the anti-virus checker check your download but for now we just let it run #yolo … )

As usual the first dialog you’ll see are the GNU License terms, your only option is to agree by clicking next or abandon the installer and start reading a good book and continue living your life without the software. Today we’ll decide to go on however …

Now select a few components. You can add some icons to the desktop and I opt for the settings to add Windows Explorer Integration and the other defaults.

I also have it install the icons on the desktop for quick access, you can always throw ‘em in the bin if you think they are in your way.

The next dialog above is for adjusting the PATH environment. My option is to “Use Git from the Windows Command Prompt”. Note that with this option you’ll be able to use both Git Bash

Bash what? …

Ok, ok, I know, if you are native from Windows you probably won’t even know what Bash is. For now, you don’t need to know other than that this is some sort of a Linux command line option.

Don’t worry, you get the hang of it once you are moved over to the ‘other side’.

Choosing the HTTPS transport backend I opted to “Use the native Windows Secure Channel library” (just because we are still in the mood of Windows, you can change this later if you like).

Configuring the line ends I leave the default as it was the recommended setting on Windows “Checkout Windows-style, commit Unix-style line endings”

You already noticed it, there is a lot of Unix influencing here … Bash, LineFeeds … it takes me back to the time I studied Computer Science. #throwbackwednesday

The next dialog is no different. Configure the terminal emulator to use with Git Bash

The option selected allows you to use both MinTTY as terminal emulator as the common Windows Console (“cmd.exe”).

Again, select the defaults to enable file system caching and enabling the Git Credential manager. Hitting Install will kick off the Git Installer to install all the selected options you entered on the dialogs above:

Done, if you want to have a quick view at what Bash is tick the option to Launch Git Bash. Otherwise it will just lead you to the Release Notes (if you didn’t remove the check before “View Release Notes” that is). You now have Git on your machine, check the version again by running git –version again.

You should see this (or a newer version if you read this later than the day of the blogpost):

Ready to go into the next step to install Yeoman.

Yeoman whaaaaaaaaaaaaaat?

Yes, Yeoman … more in my next blog post.

Hang in there and see you tomorrow! You get used to it … let it all get into your system, GoogleBing it a bit for some extra context, perform all the steps from above doing it yourself and be ready for the next step.

July 31, 2017

Office Development – Word

In my previous post I mentioned the confusion for the JavaScript APIs for Office in general. Today we’ll go deeper in and focus on the API support for the various Word clients. Let’s see what APIs are available for each of the Word clients in detail and finish off with the observations once we identified what is in each client for Word:

Word Online

Extension Points

Taskpane
Add-in Commands

APIs

Word API 1.1
Word API 1.2
Word API 1.3
Dialog API 1.1

Shared APIs

BindingEvents
CustomXmlParts
DocumentEvents
ImageCoercion
MatrixBindings
MatrixCoercion
Settings
TableBindings
TableCoercion
Text File
TextBindings
TextCoercion

Word 2013 for Windows

Extension Points

Taskpane

APIs

Dialog API 1.1

Shared APIs

BindingEvents
CompressedFile
CustomXmlParts
DocumentEvents
File
HtmlCoercion
ImageCoercion
MatrixBinding
MatrixCoercion
OoxmlCoercion
Settings
TableBindings
TableCoercion
Text File
TextBindings
TextCoercion

Word 2016 for Windows

Extension Points

Taskpane
Add-in Commands

APIs

Word API 1.1
Word API 1.2
Word API 1.3
Dialog API 1.1

Shared APIs

BindingEvents
CompressedFile
CustomXmlParts
DocumentEvents
File
HtmlCoercion
ImageCoercion
Matrix Bindings
MatrixCoercion
OoxmlCoercion
Settings
TableBindings
TableCoercion
Text File
TextBindings
TextCoercion

Note that there is a difference between the MSI installed version or the Office365 version. The MSI version only contains WordApi 1.1. according to the specifications.

Word for iPad

Extension Points

Taskpane

APIs

Word API 1.1
Word API 1.2
Word API 1.3
Dialog API 1.1

Shared APIs

Word 2016 for Mac

Extension Points

Taskpane
Add-in Commands

APIs

Word API 1.1
Word API 1.2
Word API 1.3
Dialog API 1.1

Shared APIs

Word for iPhone

–

Word for Android

–

Word Mobile for Windows 10

–

Observations

So, what do we see here? First observation is that cross platform now means that besides the good old Windows system, additional clients are limited to: “Office Online”, “Office for iPad” and “Office 2016 for Mac”. None of the phone clients have support for add-ins.

A second observation is that all other clients are more or less in par with each other. Only “Office 2013 for Windows” is limited to the DialogApi 1.1 and also none of the WordApis. It also does not support Add-in Commands. This makes you think if you should build your add-ins for Office 2013 or not at all. My guess is that the limitations on this platform are so significant that it would be better to only focus on Office 2016 and up.

Third observation is the missing support for Add-in Commands on Office for iPad. I’m curious to know why this is the case. I thought the iPad also had something like the right click (press and hold for menu) but maybe not. I don’t own an iPad -darn, do I really need to buy one now- so I can’t check this at this time.

Fourth observation is the missing Shared APIs on “Office Online”:

CompressedFile
File
HtmlCoercion
OoxmlCoercion

Maybe these four APIs are just not logical to have in an “Office Online” environment, but that too is a wild guess as I don’t know yet what it is used for.

I’m not sure yet where to go next. We now know what APIs are available for each of the Word Office clients, so I think the next step would be building a starter Add-in for Word 2016 for Windows. This client has the biggest set of APIs supported making me think that this is the best candidate to experiment on and later on see how this fans out to the other clients such as Word Online or the Apple options.

To be continued …

Sharing is caring:

Like this:

Sharing is caring:

Like this:

Sharing is caring:

Like this:

Sharing is caring:

Like this:

Sharing is caring:

Like this:

Sharing is caring:

Like this:

Sharing is caring:

Like this:

Word Online

Extension Points

APIs

Shared APIs

Word 2013 for Windows

Extension Points

APIs

Shared APIs

Word 2016 for Windows

Extension Points

APIs

Shared APIs

Word for iPad

Extension Points

APIs

Shared APIs

Word 2016 for Mac

Extension Points

APIs

Shared APIs

Word for iPhone

Word for Android

Word Mobile for Windows 10

Observations

Sharing is caring:

Like this: