Pieter van der Westhuizen

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.

Creating a new project

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#.

Selecting a programming language

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:

  • MS Excel
  • MS Word
  • MS Outlook
  • MS PowerPoint
  • MS Access
  • MS Project
  • MS FrontPage
  • MS MapPoint
  • MS Visio
  • MS Publisher
  • MS InfoPath

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

Selecting a supported applications

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.

Addin Module Designer components

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:

Designer Form

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:

Select which Office applications events to add

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:

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 :)

8 Comments

  • https://secure.gravatar.com/avatar/fba9e0b569cd5efdfa0eb71128695d53?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G ken says:

    Very good article, very informative. One thing though, I believe you’ve used the wrong event to catch mails being created. It looks like adxOutlookEvents_NewMail is an event that indicates that a new mail has been received.

  • https://secure.gravatar.com/avatar/e1a4c2b21a5186e0b27c1c601f418b76?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Pieter van der Westhuizen says:

    Hi Ken,

    You’re absolutely right. Thanks for pointing it out!
    The right event would be ItemSend. It has been fixed.

  • https://secure.gravatar.com/avatar/1469693ad1f70dee1fc61cd0cc7f70ba?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Sven says:

    Hi

    Sorry for this begginers question. So far I just worked with vba but Visual Studio is all new for me.
    Now that I have purhased your product my first exercise will be to
    1. create a new ribbon in PowerPoint (Done!)
    2. add a buttongroup (Done!)
    3. add a button (Done!)

    4. make the button to be an image (First Question:
    If I select the button in the design mode and go to the properties pane after image there is a box with a cross in it and it says ‘(none)’ afterwards. After image list it says ‘(Keine)’ . I don’t find a way to change that. How can I do so?

    5. Add functionallity: When the button gets clicked it should count the number of selected shapes in the active sheet and show the amount in a messagebox. (But only in PPNomralView otherwise show messagebox “You are not in “Normal View”!”)
    My second question: On which line do I have to insert my code? Here is the currently auto-generated code:

    Imports System.Runtime.InteropServices
    Imports System.ComponentModel
    Imports System.Windows.Forms
    Imports AddinExpress.MSO
    Imports PowerPoint = Microsoft.Office.Interop.PowerPoint

    ‘Add-in Express Add-in Module
    _
    Public Class AddinModule
    Inherits AddinExpress.MSO.ADXAddinModule

    #Region ” Add-in Express automatic code ”

    ‘Required by Add-in Express – do not modify
    ‘the methods within this region

    Public Overrides Function GetContainer() As System.ComponentModel.IContainer
    If components Is Nothing Then
    components = New System.ComponentModel.Container
    End If
    GetContainer = components
    End Function

    _
    Public Shared Sub AddinRegister(ByVal t As Type)
    AddinExpress.MSO.ADXAddinModule.ADXRegister(t)
    End Sub

    _
    Public Shared Sub AddinUnregister(ByVal t As Type)
    AddinExpress.MSO.ADXAddinModule.ADXUnregister(t)
    End Sub

    Public Overrides Sub UninstallControls()
    MyBase.UninstallControls()
    End Sub

    #End Region

    Public Shared Shadows ReadOnly Property CurrentInstance() As AddinModule
    Get
    Return CType(AddinExpress.MSO.ADXAddinModule.CurrentInstance, AddinModule)
    End Get
    End Property

    Public ReadOnly Property PowerPointApp() As PowerPoint._Application
    Get
    Return CType(HostApplication, PowerPoint._Application)
    End Get
    End Property

    Private Class CountShapes

    End Class

    End Class

  • https://secure.gravatar.com/avatar/1469693ad1f70dee1fc61cd0cc7f70ba?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Sven says:

    Sorry I was not finished:
    I assume before the last line “End Class” I add a new Private(?) Class?

    Maybe you can help me getting started with the code itself as well, so I have a good example? There was not much I could find about PowerPoint in your “adx-net-sample-projects.zip”.

    Many thanks for any help in advance.

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Sven,

    Please check https://www.add-in-express.com/docs/net-first-com-addin.php. Below I implicitly refer to that page.

    > If I select the button in the design mode and go to the properties pane after image there is a box with a cross in it and it says ‘(none)’ afterwards. After image list it says ‘(Keine)’ . I don’t find a way to change that. How can I do so?

    Put an ImageList onto the add-in module and populate it with images; specify the ImageList in the ImageList property of the button; specify the image from that ImageList in the Image property of the button.

    > On which line do I have to insert my code?

    Find the button in the in-place designer; double-click it in the right pane (in the treeview) . Alternatively, you can switch the Property window to the Events tab and add an event handler to the Click event. If you don’t know how to do this, you can google for an answer.

    > I assume before the last line “End Class” I add a new Private(?) Class?

    I’ve tried to do this and it works for me in VS 2010.

    There’s no really many code examples for powerpoint. You can search our .NET forum, see e.g. https://www.add-in-express.com/search-addin.php?q=powerpoint+view&filter=inforums-NET&by=relevance.

    If you have problems, you can contact us at the support email address, see {Add-in Express install folder}\readme.txt. Or, you can use this contact form: https://www.add-in-express.com/support/askus.php

  • https://secure.gravatar.com/avatar/1469693ad1f70dee1fc61cd0cc7f70ba?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Sven says:

    Many thanks for the fast answer.

    I will follow your tips and if necessary come back to you via mail.

    Sven

  • https://secure.gravatar.com/avatar/951fed53ffc83a0d5101bfdaddd2d02a?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Jayesh Patel says:

    Hi,
    I was following above article using add-In express. Now I am trying to deploy add-in as mentioned in “Deploy your add-in”.

    Some how I do NOT see “create setup project” option.
    Can you help me how can I do this ?
    thx

    Jayesh

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Jayesh,

    If you just can’t find the option, right-click the add-in project and choose Add-in Express | Create Setup project on the context menu. Alternatively, you can make sure that the add-in project is selected in the Solution Explorer window and choose menu Project | Create Setup Project on the main menu.

    If there’s no such option and you use an Express edition of Visual Studio, this cannot be solved: Express editions don’t support installation software products.

    If the above doesn’t help, write us using the contact form at https://www.add-in-express.com/support/askus.php.

Post a comment

Have any questions? Ask us right now!