office dev: creating an outlook add-in part 1

okay, so if you haven't downloaded it yet, why not?  visual studio tools for office 2005 second edition, aka visual studio tools for office 2007, aka vsto SE was released at devconnections earlier this month.  if you have a license to visual studio 2005 professional or a license to vsto 2005, then this is a free tool for you.

how do you get it? go here: vsto se

what is it?  it enables easy office development using visual studio.
but hasn't this been around? yes, kinda.  vsto 2005 has been there and really did make things easy.  vsto se adds support for office 2007 and makes things easier!

i seriously am loving office as a development platform these days.  i really think they've done a great job merging the office development com world with the managed code environment. 

i started looking into it when creating my sample, SnopeIt.  i currently am working on three other outlook add-ins right now that i'm going to finish, put up a screencast, and supply the source to once completed (so stay subscribed).  in the meantime, i wanted to point you to some great resources.  these are all readily available on the msdn site, but might not be elevated to a level of importance or may not be as discoverable as they should be.

right now, i've been enabling my add-ins via customizing the ribbon of microsoft office. (side note: we just announced some updates to licensing the office ui [royalty free] -- so if you are interested in leveraging the office ui experience in your applications, visit office ui licensing now.)

okay, on to geek stuff.  first, a fundamental important thing to understand when using the ribbon ui, is it's structure and how to customize it.  the simple method of doing this is providing an resource in your add-in that contains xml instructions on your custom ui.  this is a simple xml structure that looks something like this:

   1:  <customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="OnLoad">

   2:    <ribbon>

   3:      <tabs>

   4:        <tab idMso="TabReadMessage">

   5:          <group id="SnopesGroup"

   6:                 label="Snopes">

   7:            <button id="snopesButton"

   8:                    size="large"

   9:                    label="Snope-It!" 

  10:                    screentip="Search Snopes.com to check for validity" 

  11:                    onAction="OnSniff" 

  12:                    getImage="GetImage"/>

  13:          </group>

  14:        </tab>

  15:      </tabs>

  16:    </ribbon>

  17:  </customUI>

in editing in visual studio, we always love using intellisense...but the xml schema for customUI is not a part of the default intellisense.  alas, here's my first tip: use a schema file!  not only will it help you be correct, but also bring light to options you may not know about.  first, download customUI.xsd from a site. (this is supposed to be installed during the vsto install and added to the catalog, but i couldn't find it.)  i downloaded it from here: customUI.xsd.  i then put it in %ProgramFiles%\Microsoft Visual Studio 8\Xml\Schemas.  now when you open an xml file in visual studio, go to the properties pane, click on schemas and choose customUI.xsd -- boom, intellisense for ribbon customization (for the most part -- no attribute enumeration).  there is a tool on openxmldeveloper.org called the custom ui editor, but to be honest, i really didn't see value in it -- i was expecting something "more" and it wasn't there -- but feel free to take a look.

once you have this you may notice the "idMso" attributes in the sample above.  what are these?  well, they are the office built-in control ids...and very helpful.  in some instances it will allow you to customize their use, but in most instances it will help you place your customization.  in the sample above, my add-in will reside in the Message tab of an item being read.  the idMso attributes are well documented in this document: office 2007 list of control ids.  install this document set and leverage it -- it will help you and be a valuable resource.

one caveat that i've just discovered is that you cannot add your add-in controls (i.e., a button) to an existing ribbon group.  for example if i wanted my SnopeIt to be in the Other Actions group, i couldn't.  apparently there is some thought out reasoning why not, but i don't necessarily agree with it (i mean, if mine is another action, it would make sense that to maintain usability i'd keep it there in the 'other actions' group).  just know that.  but you can control where your addin group is placed.  in your group, again using the intellisense will help you here, you will see an attribute called insertBeforeMso (and insertAfterMso) where you specify the control id of the group you want it before/after.  again, look at the list of control ids.

okay, and last tip for now...debugging.  by default your office client will not show errors in your ribbon customization -- not good if you don't see your customization and don't know why.  for example, in outlook 2007, go to tools, options, others (tab) advanced, and enable "show add-in user interface errors" -- if your addin won't load due to a violation/error in the ribbon customization, you'll see the reason here.  this has helped me.

that's it for now -- there are some great tutorials on getting started, and i'll document my add-ins (which are a little more useful [hopefully] than SnopeIt, but still fun).