Migrating a VS2019 Office Web Add-in to VS Code

I find myself frequently converting Office Web Add-in projects I originally created in VS2019/2017/2015 over to VS Code. This is because VS Code has become my preferred development platform for everything Web based.

There is a trick to this and a few things you need to know:

1. Your project in VS2019 (et. al.) has a completely different structure, so once you move things around, you need to change some references.
2. If you use the Yeoman generator to create the shell of your new project, you need to know a little about webpack.

So, in the following sections we will cover what you need to do:

• Copy over all the files
• Update the references
• Add web pack commands

Copy Files

1. Run “yo office” and create a default taskpane add-in, with JavaScript and for Outlook. This will create your baseline project. You will open this project and delete these files:
   1. .\src\taskpanes\taskpane.html
   2. .\src\taskpanes\taskpane.js
   3. .\src\commands\commands.html
   4. .\src\commands\commands.js
   5. .\assets\*.* (delete everything in there)
2. In your VS2019 project and then open your Manifest (highlighted in the image below). Select All and Copy everything from the manifest.

3. Open your shell project in Visual Studio Code, open the manifest.xml and paste. Later we will update the references.
4. Next, copy the VS2019 FunctionFile.html and FunctionFile.js files to the .\src\commands folder in VS Code, then rename both: commands.html, commands.js
5. Next, copy your VS2019 taskpane.html and taskpane.js to the taskpanes folder in VS Code.
6. If you are like me and also have dialogs, you can create a .\src\dialogs folder in VS Code and then copy the dialog.html and dialog.js from VS2019 to VS Code.
7. Be sure to copy over any other supporting scripts you have. I created a folder called .\src\common in VS Code and copied those JS files from VS2019.
8. Next, anything you have in the Content folder in VS2019 you need to copy to VS Code .\assets folder.

That is it for the copy part. Now for the manifest part.

Update the Manifest

At this point you need to update the manifest.

1. Open the manifest.xml in VS Code and Press CTRL+H to open the Find/Replace dialog. Type in ~remoteAppUrl and replace it with https://localhost:3000. Then replace all instances.
2. Next and this part is a bit more tricky, but you need to look at every single html pointer URL and verify that it points to the ROOT. Meaning if it was [~remoteAppUrl/Functions/FunctionFile.html] and then you did the Find/Replace, it became [https://localhost:3000/Functions/FunctionFile.html]. You need to update this to be just: https://localhost:3000/FunctionFile.html. This is because when you compile your project with Web Pack, it places everything in the root.
3. Again, this is tricky, but every one of your base URL’s for images will need to be updated to point to the correct image in the ./assets folder.
4. Once you have completed, you can press CTRL+~ to open the command console and type: npm run validate. This will tell you if there is anything wrong with your manifest.

Update the HTML files

Next you need to open up each of your HTML files: dialogs.html, commands.html (was called FunctionFile.html), and taskpane.html. etc. In each of these you will find a script that points to a respective JavaScript file and possibly other source files you copied over to the .\src\common folder. Remove all those script tags. Leave only the tags that point to online CDN’s. We will get to this in one of the following sections, but essentially Web Pack will put all the references in for you automatically at compile time.

Also, any images that you are referencing in your HTML with the <img> tag will need to be updated to point to the proper file in the ./assets folder.

Update the Commands.js (formally FunctionFile.js)

Now we need to get everything ready for Web Pack and that is where we start getting into some code. I will cover Web Pack in another post soon, but what it uses is a global namespace for the functions you call. So you MUST add this code to the bottom of the JS file:

	/*************************************************/
	/* REQUIRED BY WEB PACK – DO NOT DELETE */
	/*************************************************/
	function getGlobal() {
	return typeof self !== "undefined"
	? self
	: typeof window !== "undefined"
	? window
	: typeof global !== "undefined"
	? global
	: undefined;
	}
	const g = getGlobal();
	g.onSendEvent = onSendEvent;
	g.onRibbonButtonClick = onRibbonButtonClick
	/*************************************************/
	/* REQUIRED BY WEB PACK – DO NOT DELETE */
	/*************************************************/

view raw webpack _required.js hosted with ❤ by GitHub

In your manifest you have specified the functions that will be called when the user clicks on a Ribbon button or Events that will fire such as OnSend in Outlook. Find those function and made sure they are added to the global namespace as shown.

Also, at the top of EVERY single JS file in your project you will need to add the following line:

/* global global, self, window, Office, console, myClass*/

When you start to edit these files in VS Code, there will be a whole lot of “red squigglies” for undefined items in the global space. For each of those that the syntax highlighter defines as such, you will add it to the global tag at the top of the file. Like this:

Update the Common JS Files

For the .\src\common files any function you want to be available in the global namespace, meaning you call it from one JS file to the next, you will want to add the same section above and make sure the function is specified.

NOTE: You will also want to do this for any global constants or vars that you want visible as well.

Update the Web Pack Config

Finally, we have to update the webpack.config.js. This is probably the most tricky part. What you need to do is locate the values for {entry} and make sure that every JS file in your project is represented:

	entry: {
	polyfill: "@babel/polyfill",
	dialog: "./src/dialogs/dialog.js",
	commands: "./src/commands/commands.js",
	shared: "./src/common/shared.js",
	common: "./src/common/common.js",
	taskpane: "./src/taskpane/taspane.js"
	},

view raw entry.js hosted with ❤ by GitHub

NOTE: This is critical to get correct and to include all JS file because if you do not do this, it will not work.

Now that you have all the entries in place you need to update the {plugins} section. You might need to create an extra module or two as well. By default you have one for taskpane and commands, but my example will show dialogs as well:

	plugins: [
	new CleanWebpackPlugin(),
	new HtmlWebpackPlugin({
	filename: "taskpane.html",
	template: "./src/dialogs/taskpane.html",
	chunks: ["polyfill", "common", "shared", "taskpane"]
	}),
	new HtmlWebpackPlugin({
	filename: "dialog.html",
	template: "./src/dialogs/dialog.html",
	chunks: ["polyfill", "common", "dialog"]
	}),
	new HtmlWebpackPlugin({
	filename: "commands.html",
	template: "./src/commands/commands.html",
	chunks: ["polyfill", "shared", "commands"]
	})
	],

view raw plugins.js hosted with ❤ by GitHub

Note how in each plug-in (the HTML file), there are “chunks.” These chunks are the references to each script tag that will be added at compile time. It is VERY important to make sure that you reference each file as expected.

Ready to Test

At this point you should be ready to test. If you manifest validated, you can now just press CTRL+~ to open the command console and type npm start.

If your solution successfully sideloads in Office, you should verify that your commands, events and taskpanes all function. If they do not here are some common issues:

1. You did not properly reference your JS file in the webpack.config.js. Either defined as an {entry}, or as a chunk on a {plugin}.
2. You did not add the required code at the bottom of the JS file for your functions to be defined in the global namespace, or you forgot to add one or more.
3. Your manifest is not pointing to the right file. Remember, once Web Pack compiles your code, everything is in the root, except for the assets.

That is a lot, I am sure I missed a few things even though this post took me a while to write. If you have any issues with porting over your project and find there are some missing steps or something I can clarify more, please let me know.