Add-in Express 2010 and Office add-ins: Getting started

I have used Add-in Express before and can honestly say that if you want to develop an MS Office add-in this product is definitely a worthwhile investment. In this post I'll explain the benefits and some of the key features of Add-in Express 2010 for Office and .net when creating a small Office Add-in that is shared among Excel, Word and Outlook.

Where to start

Creating your first Add-in Express project is a very easy process, after installing and activating the product, start up Visual Studio. In this scenario we'll be using Visual Studio 2010, but Add-in Express 2010 for Office and .net will work with all versions (2003 to 2010) and editions (Express to Ultimate) of Visual Studio.

In Visual Studio, create a new project and select the ADX COM Add-in project, available under Other Projects Types>Extensibility.

Version neutrality and the language of your choice

When creating a new Add-in Express project you are presented with the new project wizard. In the first screen you are able to choose whether you would like to develop an MS Office version neutral Add-in (this means your add-in will work on MS Office 2000 up to MS Office 2010) or the currently installed version of Office. In the proposed case study we would prefer to have a big market for our add-in so we'll go the version neutral route. You can use your favourite .Net language but for this case study we'll be using C#.

Shared add-in? No problem

Enabling your add-in to be shared among multiple Office applications is as easy as selecting a couple of checkboxes. You can develop add-in for the following products in the Microsoft Office suite:

We're doing a shared add-in for Excel, Word and Outlook, so select the boxes next to each of these options to continue.

When prompted to generate a string key, select New and Finish.

Entry points

Let's have a quick look at what the solution layout looks like. You'll notice that it is pretty straight forward, the project creation wizard did a lot of work behind the scenes, but to all intent and purpose we'll only be interested in the AddinModule class. This class is where all the magic happens. First thing you'll notice is 3 properties that would come in very handy. When creating a new project and selecting the applications among which the add-in needs to be shared, the project creation wizards adds a read-only property for each application that will allow you to access MS Office application specific features. The beauty of this is, you do not need to create multiple projects in order to share logic amongst MS Office applications. We'll refer to these properties as entry points. The code looks like this:

public Excel._Application ExcelApp
{
	get
	{
		return (HostApplication as Excel._Application);
	}
}
 
public Word._Application WordApp
{
	get
	{
		return (HostApplication as Word._Application);
	}
}
 
public Outlook._Application OutlookApp
{
	get
	{
		return (HostApplication as Outlook._Application);
	}
}

Addin Module

Let's take some time and look at the AddinModule a little closer. At the moment it only contains a couple of MS Office application entry points and some auto generated code which you do not need to change. Select the AddinModule class and click on the View Designer button. You are presented with a big grey nothing…just kidding ;). Glancing over to the properties window you'll notice a range of properties that could come in very handy, I'm going to highlight 2 of my favourites:

• FolderPages
  This is only available for MS Outlook. It will give you the functionality to replace the properties window of any Outlook folder. For example, if your add-in creates its own folder, by setting the FolderPages property you can replace the folders' default properties page with your own form and logic.

• TaskPanes
  You can easily create task panes that can contain your own forms and logic. You can also set the SupportedApps property to confirm in which MS Office application the task pane should be visible.

We'll delve deeper into how to use these properties at a later stage. Next we'll have a quick look at how to add a simple UI to the 3 Office applications we've selected, i.e. Outlook, Excel and Word.

The UI

Right-click on the AddinModule's designer, you'll notice a host of available components available to you.

Select Ribbon Tab, on the Ribbon Tab's properties click the ellipse (…) button, next to the Controls property. Add 3 Ribbon Groups, one for each application we want our add-in to run in (e.g. Excel, Word and Outlook). For each Ribbon Group, you must set the Ribbons property to the application you want each specific group to be shown in e.g. the Excel group, make sure only the ExcelWorkbook checkbox is selected. Also, add a button to each group. The designer form should look something like this:

Accessing Office objects

Excel

Next, we'll write some code to do Office Application specific actions. For Excel we'll use the ExcelApp property to access Excel specific operations. We'll add an event handler for the Excel button and add the following code to it:

void adxRibbonButton1_OnClick(object sender, AddinExpress.MSO.IRibbonControl control, bool pressed)
{
    Excel.Worksheet activeSheet = null;
    Excel.Range range = null;
    try
    {
        activeSheet = (Excel.Worksheet)ExcelApp.ActiveSheet;
        range = activeSheet.get_Range("A1", Type.Missing);
        range = range.get_Resize(1, 2);
        range.Value = "ADX.Net";
    }
    finally
    {
        if (range != null)
            Marshal.ReleaseComObject(range);
        if (activeSheet != null)
            Marshal.ReleaseComObject(activeSheet);
    }
}

Notice, how we've used the ExcelApp property to get a reference to the running instance of Excel. No need to add any references, Add-in Express project wizard does all that for you. From there it's standard Office development, of which you can find numerous examples on the internet.

Word

Follow a similar approach for the Word part of our add-in, add an event handler for the Word button, in case your wondering what that code looks like here it is:

adxRibbonButton2.OnClick += new AddinExpress.MSO.ADXRibbonOnAction_EventHandler(adxRibbonButton2_OnClick);

You can add this code in the AddinModule's constructor. In the eventhandler add the following:

void adxRibbonButton2_OnClick(object sender, 
	AddinExpress.MSO.IRibbonControl control, bool pressed) 
{
	Word.Document activeDoc = null;
	Word.Range docContent = null;
	Word.Paragraphs docParagraphs = null;
	Word.Paragraph newParagraph = null;
	Word.Range newParagraphRange = null;
	Word.Font newParagraphFont = null;
	Word.ParagraphFormat newParagraphFormat = null;
 
	try
	{
		activeDoc = (Word.Document)WordApp.ActiveDocument;
		docContent = activeDoc.Content;
		docParagraphs = docContent.Paragraphs;
		newParagraph = docParagraphs.Add();
 
		newParagraphRange = newParagraph.Range;
		newParagraphRange.Text = "ADX.Net 2010 Rocks!";
 
		newParagraphFont = newParagraphRange.Font;
		newParagraphFont.Bold = 2;
 
		newParagraphFormat = newParagraph.Format;
		newParagraphFormat.SpaceAfter = 10;
 
		newParagraphRange.InsertParagraphAfter();
	}
	finally
	{
		if (newParagraphFormat != null)
			Marshal.ReleaseComObject(newParagraphFormat);
		if (newParagraphFont != null)
			Marshal.ReleaseComObject(newParagraphFont);
		if (newParagraphRange != null)
			Marshal.ReleaseComObject(newParagraphRange);
		if (newParagraph != null)
			Marshal.ReleaseComObject(newParagraph);
		if (docParagraphs != null)
			Marshal.ReleaseComObject(docParagraphs);
		if (docContent != null)
			Marshal.ReleaseComObject(docContent);
		if (activeDoc != null)
			Marshal.ReleaseComObject(activeDoc);
	}
}

Once again, notice how easy it is to access the current running instance of Word's properties? You can add a simple paragraph, once again using standard Office development code.

Outlook

Next, we'll tackle one of my favourite Office applications to customize. Outlook is such a powerful collaboration tool, with so much untapped potential. One thing you need to remember is that Outlook is a bit different as you have a lot more options on where to display your Ribbon UI. For this example we'll limit it to an e-mail that we received, so set your Ribbons property to OutlookMailRead.

Using the OutlookApp property we'll write some logic to show a list of recipients on an e-mail. Right, first things first, hook up an event handler for our Outlook button. And the code that does the magic will look something like this:

void adxRibbonButton3_OnClick(object sender,
	AddinExpress.MSO.IRibbonControl control, bool pressed)
{
	Outlook.Explorer activeExplorer = null;
	Outlook.Selection activeSelection = null;
	Outlook.MailItem mailMessage = null;
	Outlook.Recipients mailRecipients = null;
	Outlook.Recipient mailRecipient = null;
	string recipientList = string.Empty;  
 
	try
	{
		activeExplorer = OutlookApp.ActiveExplorer();
		activeSelection = activeExplorer.Selection;
		mailMessage = activeSelection[1] as Outlook.MailItem;
 
		mailRecipients = mailMessage.Recipients;
 
		for (int i = 1; i <= mailRecipients.Count; i++)
		{
			mailRecipient = mailRecipients[i];
			recipientList += mailRecipient.Name;
			if (mailRecipient != null)
				Marshal.ReleaseComObject(mailRecipient);
 
		}
		MessageBox.Show(recipientList);
 
	}
	finally
	{
		if (mailRecipients != null)
			Marshal.ReleaseComObject(mailRecipients);
		if (mailMessage != null)
			Marshal.ReleaseComObject(mailMessage);
		if (activeSelection != null)
			Marshal.ReleaseComObject(activeSelection);
		if (activeExplorer != null)
			Marshal.ReleaseComObject(activeExplorer);
	}
}

I had to add a reference to System.Windows.Forms in order to use Messagebox.Show.

Office events

Capturing Office events is a very easy task using Add-in Express for Office and .net, let's say for example you want to display a message every time a user creates a new email informing them of the IT policy (a bit draconian, I know, but bear with me). So in order to accomplish this we need to trap Outlooks' Create new Email Event. Going back to the AddinModules' designer, select Add Events from the context menu. You'll be prompted with a form to select which Office applications events to add, select Outlook:

A component named adxOutlookEvents will be added to the designer, if you select it and view its events you'll notice a whole list of events you can use. Double click in the ItemSend event in order to generate the event handler code. Now, you can add any custom logic that needs to run as soon as the user creates a new mail message. For our example, it'll look like this:

private void adxOutlookEvents_ItemSend(object sender, EventArgs e)
{
     MessageBox.Show("Remember the IT Policy!");
}

Testing your add-in

Now, that you've written all the code, it's time to test your add-in. In the Visual Studio Solution Explorer right click on the project and select Build, once the project has built successfully, choose Register ADX Project from the same context menu. This will register your add-in in the necessary Office applications. Once that has completed start up Excel and you'll notice a new Ribbon Tab:

The same will apply for Word and Outlook. Now, that you've written your add-in, the next step would be to deploy it to customers.

Deploying your add-in

Deploying your add-in could not be simpler Add-in Express for Office and .net takes care of all the leg work for you. To generate a setup project, right click on your project, and select Create Setup Project from the context menu. Specify your product and company name, click Next, and you can specify localization, the setup file name and the output folder. Add-in Express goes to work creating the setup project for you. All you need to do in order to deploy your add-in is build the setup project and give your user the setup files. You also have the option to use click-once deployment, but that is for another post.

Wrapping Up

This was a whirlwind trip through just some of the amazing capabilities of Add-in Express for Office and .net. For more on how to use it and how it can save you tons of time and unnecessary work, visit the folks at Add-in Express. Tell them I referred you.

Until next time, keep coding :)