[O365] Getting started with yo office for hardcore C# devs

Technical / November 9, 2015 / Jasper Siegmund / 8

I’ll immediately admit that I’m a Microsoftie. 100%. I have Visual Studio installed, feel at home in C# and get a rash sometimes from dealing with JavaScript nonsense. But let’s be honest, unless you’re not doing ANYTHING with the web it’s almost impossible to ignore trending technologies like nodejs, angular and all of the other frameworks that live online. And because I don’t want to be the ignorant fool who has a lot of catching up to do in a couple of years time, I thought I’d give it a go on a stormy Monday evening. 

My project of choice is doing an Office add-in. For those of you unaware, the recent versions of Office support add-ins which are best described as iframes in your Office clients (online and offline) showing an add-in in the form of HTML and JavaScript. Now for clarity; it’s perfectly possible to create an add-in using your trusted Visual Studio 2015 (and 2013 too) installation. But that’s NOT what I’m covering in this post. Instead, I’ll be using some other neat stuff which lies just outside of my normal coding comfort zone.

Yeoman generators

“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.
• tsd: crap, another package manager!? Yes and this one specializes in TypeScript definition files. If you’re not familiar with TypeScript yet, it’s a typed language which compiles to (untyped) JavaScript. If you’re familiar with C# and a little bit of JavaScript, you’ll won’t need much adapting to learn TypeScript.

Yo Office!

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:

yo office

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:

code .

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.

Ahhh, now that at least looks kind of familiar, right? Well since it’s just HTML and JavaScript, you can easily use this editor to make changes to your app. To keep this blog post somewhat short I’ll cover that in a future one.

Hosting

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:

gulp serve-static

to have your add-in running in the browser in no-time! Again, it’s just HTML and JavaScript so you can also create a virtual directory in IIS and serve it that one. Use Apache for all I care, as long at the thing can be reached somewhere. One thing that’s important to keep in mind is that https is required as soon as you want your add-in to show in Office. No SSL, no party, not even in development scenarios.

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.

#office365dev, in

Jasper Siegmund