Building and deploying an Outlook 2010 Add-in (part 1 of 2)

So, you’ve cracked open your shiny new Visual Studio 2010, and you would like to build and roll out an add-in for Outlook 2010 (we’re using Outlook here, but most of the principals apply to Word and Excel also)?

In this post (part 1), I’ll take you through the steps required to build a ribbon that appears on the Home screen, as well as a tab in the “backstage” area. (new features that are only available in Outlook 2010). In part 2, we will go through the steps required to create a setup project that will deploy the add-in.

Getting started

NewProject_1_77889157 First, let’s create our project. Within Visual Studio 2010, using the language of your choice, create a new Office 2010 project with the “Outlook 2010 Add-in” template.

We are going to add a ribbon control to the project. There are 2 ways you can do this – either by adding a ribbon xml file, or a ribbon visual designer. We’re going to use the best of both worlds – configuring our ribbon with a visual designer, and then converting it to xml when we are done.

Add a Ribbon

Right click on the new project in Solution Explorer, and select Add – New Item…. In the window that appears, select ‘Office’ in the the left-hand box, and then add a new Ribbon (Visual Designer). On the design surface that appears, you should see a blank ribbon. In this example we are going to add one button, but you will probably want to add a fair bit more until you have all the appropriate controls.

Open the Toolbox tab, and drag a button into group1 (groups are used to separate areas of functionality) on the toolbar. Set the ControlSize to RibbonControlSizeLarge, and add an image to the button. Double click on the button to open the event handler code for the button click, and add some simple code, like below:

 private void button1_Click(object sender, RibbonControlEventArgs e)
{
    System.Windows.Forms.MessageBox.Show("Your Ribbon Works!");
}

Now, we need to configure the add-in so that it will display correctly in Outlook - we want it to appear as a separate tab on the Home screen (the default behaviour is to add the ribbon to the “Add-in” tab on the mail reading screen). In the ribbon designer, click on the tab where it says “TabAddIns”, and then open the Properties window. You will need to set the following properties on the ribbon tab:

  • Expand the ControlId property, set ControlIdType to “Custom”
  • Set the (Name) to “MyOutlookTab” (or whatever you want to call it)
  • Set the Label to “MyOutlookTab”

Click on the Designer in the top left where it says “Ribbon1”, and configure properties for the Ribbon itself:

  • Set the (Name) to “MyOutlookAddIn”
  • On RibbonType, uncheck Microsoft.Outlook.Mail.Read, and check Microsoft.Outlook.Explorer

Now run your project (make sure Outlook is closed), and you should see something like this:

Ribbon_1_77889157

OK, we have made our basic ribbon, but before we are done, we will add a ‘Backstage’ tab to our add-in. We’re going to do this by converting our Ribbon from a visual designed one into an XML based one (editing the Backstage is not currently supported through the visual designer). To do this, click on the link at the bottom of the Properties window when the ribbon is selected – titled “Export Ribbon to XML”. This will create 2 new files, Ribbon.cs, and Ribbon.xml. You will now need to make a few simple code changes in order to get your XML–based ribbon solution working; but before we do that, let’s get on and add the mark-up for the Backstage.

The Backstage

Quite simply, the backstage is the area you see in Office 2010 applications when you click on the “File” tab. You can add your own, custom tabs to this area by adding mark-up, which we will do (very simply) here. Firstly, to make life easier, download the Office 2010 Custom UI Schema, which will give you IntelliSense in the XML document. Then:

  • Change the namspace referred to in ribbon.xml to point to https://schemas.microsoft.com/office/2009/07/customui
  • In the properties window, ensure that the above schema is referenced (Schema property)
  • Add the following XML blob (just the tag element with an id of MyBackstage – the rest is included for info):
 <?xml version="1.0" encoding="UTF-8"?>
<customUI onLoad="Ribbon_Load" xmlns="https://schemas.microsoft.com/office/2009/07/customui">
    <ribbon>
        <tabs>
            <tab id="MyOutlookTab" label="MyOutlookTab">
                <group id="group1" label="group1">
                    <button id="button1" onAction="button1_Click" label="button1" size="large" />
                </group>
            </tab>
        </tabs>
    </ribbon>
    <backstage>
        <tab id="MyBackstage" label="MyBackstage" columnWidthPercent="30" insertAfterMso="TabInfo" visible="true" >
            <firstColumn>
                <group id="grpOne" label="Group One">
                    <primaryItem>
                        <button id="buttonBackStage" label="button Backstage" onAction="buttonBackStage_Click"/>
                    </primaryItem>
                </group>
            </firstColumn>
        </tab>
    </backstage>
</customUI>

You’ll notice we have added a button to our backstage (buttonBackstage), that has an onAction event. Let’s hook that up now (as well as the button we added to our Ribbon). Open up Ribbon.cs:

  • At the top of Ribbon.cs file – you will see some instructions that need to be followed – make sure you do point one by copying the code below into ThisAddIn.cs:
 protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new Ribbon();
}
  • Now, create event handlers for each of the buttons we have created in Ribbon .cs (the “onAction” attribute points to the method that will be called):

 

 public void Ribbon_Load(Office.IRibbonUI ribbonUI)
{
    this.ribbon = ribbonUI;
}

public void button1_Click(Office.IRibbonControl control)
{
    System.Windows.Forms.MessageBox.Show("Your Ribbon Button Works!");
}

public void buttonBackstage_Click(Office.IRibbonControl control)
{
    System.Windows.Forms.MessageBox.Show("Your Backstage Button Works!");
}

Finally, delete or exclude Ribbon1 from your project (you don’t need it now as you have moved the functionality into ribbon.xml), and you are ready to go! You should see a new tab in your back stage that looks something like this:

Backstage_2575E410

 

So, the add-in is all ready, and it works on your machine, right? In my next post, we’ll go through the steps to build a setup package that you can use to deploy the add-in to other users.

Written by Matthew Farmer