[O365] Getting started with yo office for hardcore C# devs
“Say whut?” was exactly my reaction when I first heard about this for the first time. Yeoman is this dude:
Who is apparently named after / inspired by some English wardens at the Tower of London (https://en.wikipedia.org/wiki/Yeoman). Anyways, more important to know is that Yeoman is also a scaffolding framework for web projects. A Yeoman generator therefore, is a generator that generates project scaffolding for you to use as a starting point. Now the cool thing is that some guys (like Andrew Connell and Waldek Mastykarz) spent some time building such a generator for Office add-ins. So that allows you to build the scaffolding for your project like you would normally do using the Visual Studio Wizard.
First things first
I used the example from dev.office.com you can find here. That article starts with installation of some bits and pieces using a console line and the “npm” command. But note that there is one step that should actually be done first: install nodejs! NPM is nodejs’ package manager and so you need to have node installed on your PC first. To do so, simply head to nodejs.org, download and install.
After installing node, you can start the “Node.js command prompt” from the start menu. This gives you the console you need and now you can install the bits and pieces you need using:
npm install -g bower yo generator-office gulp tsd
This will install a bunch of packages which we’ll need to complete the process. I
googled binged these to find out what they are:
- bower: another package manager, but one especially for front-end stuff (which doesn’t go for NPM). This stackexchange post has an answer which contains all the info you need.
- gulp: is about automating your build process, eliminating manual stuff (yay, I’m a fan already). You can set up all kinds of task, for instance to host your project. Read more about what it is and why you need it here.
Ok so we’ve got some stuff installed now, time to fire up the generator! Doing so is easy AND cool at the same time, just type into the nodejs console:
You’ll be welcomed by the same Yeoman dude again, this time rendered in ASCII (who doesn’t dig that):
What follows is a wizard which will ask you some questions like the project name, where to store it (path), what type of add-in (Outlook, Word), and some more depending on the add-in type. I filled everything in and watched it fail:
Ah, another hidden dependency, provided you also didn’t have git installed on your PC. You need to have git installed, which is the source code management tool used by all those open source hippies out there. Allright, another download you can find here: https://git-scm.com/download/win. During installation I chose to use the windows command prompt and integrate the git commands, I’m not sure that’s required though.
After installing, you need to restart the nodejs command prompt so the new git commands can be used. Type “yo office” again and complete the wizard. Note that you might want to clear out the directory beforehand as your previous attempt will have left some garbage.
You next attempt should be more successful. After a few seconds everything will have been downloaded and your project will have been created on disk.
Visual Studio Code
Don’t look for a .sln or .csproj file, you will not find them. Instead, you can now use any text editor tool you like to open and edit the files. Might be a cool opportunity for you to try out Visual Studio Code which is a lightweight version of the tool you love. Download it here and after installing, simply type:
in the nodejs console (or normal command prompt) to fire it up. You might need to reboot your console before it knows about code, not entirely sure about that as I already had it installed.
Now we’ve got our add-in, we need to host it somewhere since Office will try to open a URL where our add-in should be. This is nicely covered in the how-to article mentioned before so I’ll won’t go into too much detail. The Yeoman generator already set up a gulp task to get you going, which is named serve-static. That means you can just type in:
Adding add-in to add-ins in Office365
Last but not least, you probably want your add-in to actually show within Outlook or other Office clients. Once again I’d like to refer to the howto guide, with one addition. Make sure you edit your manifest-[add-in name].xml file before you try to load it into Office 365. Fresh out of the generator, it will contain these lines:
<Description DefaultValue="[Task pane Add-in description]"/> <HighResolutionIconUrl DefaultValue="[Icon URL]"/> <SupportUrl DefaultValue="[Support URL]"/>
Obviously “[Icon URL]” and “[Support URL]” are not valid URLs so you need to replace these to prevent Office365 from telling you you really should replace ’em. Throw in a nice description too whilst at it.
When the file is loaded, fire up the client application of choice and select the add-in. In my case I created a compose add-in for Outlook, which is visible when you click “Office Add-ins” in the compose pane:
Of course your add-in is still empty since you’ve only got scaffolding now. Head over to http://blog.repsaj.nl/index.php/2015/11/o365-my-first-add-in-using-yo-office/ for part 2 of this blog on how to implement an add-in.