In a minute I will tell you how to use these events, uncover their drawbacks, and show how to use the MAPI Store Accessor to bypass negative sides of these events in .NET.

NewMail

Notwithstanding its name, this event fires at a few minute intervals. It ignores any incoming items which arrived shortly after a previous NewMail event. Another limitation makes the NewMail event almost useless – if more than 16 items arrive at once, the event will not fire at all!

NewMailEx

This event was introduced in Outlook 2003. It improves monitoring of incoming messages by providing access to EntryIDs of newly arrived e-mails. EntryIDs are separated with commas in a string parameter of the NewMailEx event. You can easily get any item using its EntryID:

NameSpace.GetItemFromID(EntryID)

Well, this method has restrictions of its own. Say, if more than 1000 items come at once, some of them may be missing. That is, you can’t rely on the NewMailEx event alone. You may want to regularly check for unprocessed messages, say by using a timer.

ItemAdd

You can also use the ItemAdd event of the Items collection of Outlook folder class (MAPIFolder in Outlook 2000-2007, Folder in Outlook 2007). This is especially useful when you need to check new mails in some other folder, say, another user’s Inbox. However, note that ItemAdd will not fire if more than 16 items are added at the same time. This restriction has the same root as that of the NewMail event. For instance, Microsoft writes that “this is due to Microsoft Exchange Server and MAPI using different methods when moving large amounts of data. Outlook does not take this into account and therefore the event fails to fire in those cases.”. They also suggest periodically checking the number of items in the folder to see if there are new items.

MAPI

MAPI enables you to bridge the gap between Outlook events and developers’ demands. You can use our MAPI Store Accessor which connects to the MAPI subsystem and subscribes to selected events at the MAPI level. As a result, you will get all needed notifications such as NewMail, ObjectModified, ObjectDeleted, etc. No restrictions of mentioned above. But, alas, in this case there is the other side of the coin, too. If you use Exchange Server in a profile you may encounter situations in which you don’t get a needed event notification such as OnNewMail. The reasons may be:

• The Mapi Store Accessor connects to the MAPI subsystem after the first synchronization between Outlook and Exchange (i.e. when Outlook loads). That is, you will not get notifications for all e-mails that were received before the MAPI Accessor initialize subroutine. To solve this problem you can try to use Exchange Client Extensions. You can read more in an article in MSDN.
• You close Outlook before event notification arrived and that is why you do not get it anymore. To resolve this issue you have to track all items and check by timer for new items. For instance, you can use ReceivedTime or set user properties on arrived emails and is this way you can recognize old and new ones. Certainly you can choose your own way of tracking new emails.

My experience shows that for Exchange server profiles, an event notification may delay for an on an arbitrary period. Some developers mistakenly reported that event notification didn’t work with Exchange server. In fact, they missed event notifications when closing Outlook immediately after the event had occurred.

Eugene Astafiev
Add-in Express Team

Localizing command bar controls

Pay attention to the AddinInitialize event of the add-in module (OnAddInInitialize in the VCL edition). Its event handler is the best place to check the localization of the Office application and modify all user-visible properties of your command bar controls. Note that this event fires before any custom command bar is added to the command bar system of the host application.

When localizing command bar controls in Add-in Express, make a clear distinction between temporary and non-temporary (permanent) controls. Temporary command bar controls are created every time the add-in starts and are removed when the host application closes or the add-in is checked off in the COM Add-ins dialog. In the following code, it is assumed that AdxCommandBarButton1 is a temporary command bar button. That is, its Temporary property is set to true.

   Private Sub AddinModule_AddinInitialize(ByVal sender As Object, ByVal e As System.EventArgs) _
      Handles Me.AddinInitialize
      Dim LCID As Integer
      LCID = Me.HostApplication.LanguageSettings. _
         LanguageID(Office.MsoAppLanguageID.msoLanguageIDUI)
      Select Case LCID
         Case 1033 'English
            AdxCommandBarButton1.Caption = "English Caption"
            AdxCommandBarButton1.TooltipText = "English Hint"
            AdxCommandBarButton1.DescriptionText = "English Description"
         Case 1036 'French
            ...
         Case 1031 'German
            ...
         Case 1040 'Italian
            ...
         Case Else ' isn't supported - use English
            ...
      End Select
   End Sub

See how to implement the same approach in VCL (Delphi):

procedure TAddInModule.adxCOMAddInModuleAddInInitialize (Sender: TObject);
begin
  case HostApp.LanguageSettings.LanguageID[msoLanguageIDUI] of
  1033: begin // English
    CommandBar1.Controls[0].AsButton.Caption :=
                                             'English Caption';
    CommandBar1.Controls[0].AsButton.TooltipText :=
                                                      'English Hint';
    CommandBar1.Controls[0].AsButton.DescriptionText :=
                                                  'English Description';
  end;
  1036: begin // French
    ...
  end;
  1031: begin // German
    ...
  end;
  1040: begin // Italian
    ...
  end;
  else begin // not supported - use English
    ...
  end;
end;

Non-temporary controls are created at the first start of the add-in. They are removed when you uninstall the add-in or uncheck it in the COM Add-ins dialog in the Office application. So, if AdxCommandBarButton2 has the Temporary property set to false, the following code should be used:

   Private Sub AddinModule_AddinInitialize(ByVal sender As Object, ByVal e As System.EventArgs) _
      Handles Me.AddinInitialize
      If Me.StartMode = AddinExpress.MSO.ADXStartMode.smFirstStart Then
         Dim LCID As Integer
         LCID = Me.HostApplication.LanguageSettings. _
            LanguageID(Office.MsoAppLanguageID.msoLanguageIDUI)
         Select Case LCID
            Case 1033 'English
               AdxCommandBarButton2.Caption = "English Caption2"
               AdxCommandBarButton2.TooltipText = "English Hint2"
               AdxCommandBarButton2.DescriptionText = "English Description2"
            Case 1036 'French
               ...
            Case 1031 'German
               ...
            Case 1040 'Italian
               ...
            Case Else ' isn't supported - use English
               ...
         End Select
      End If
   End Sub

Delphi developers write the conditional statement in their own way:

  if Self.StartMode = smFirstStart then

When localizing custom .NET controls to be embedded onto Office toolbars, you use one of the approaches above depending on the value of the Temporary property of the corresponding AdvancedCommandBarControl. Note, that you need to localize the control specified in the AdvancedCommandBarControl.Control property.

Localizing Ribbon controls

Office 2007 Ribbon controls are created when the add-in starts. They are removed whenever the add-in unloads. You can localize the controls in the OnRibbonBeforeCreate event of the add-in module.

The only exception to this rule is the dynamicMenu Ribbon control. It provides the OnCreate event that allows populating the component with controls. Naturally, this event is suitable for localizing the controls.

Localizing Office 2007 Task Panes

In .NET, a task pane is a UserControl an instance of which is created whenever the task pane is shown. The instance is removed when the task pane is destroyed (see the OnTaskPaneBeforeDestroy event of the add-in module). To localize the task pane, use the Load event of the UserControl.

In Delphi, a custom Office task pane is a descendant of TActiveForm and you use its OnCreate event. For instance:

procedure TmyPane.ActiveFormCreate(Sender: TObject);
begin
  case ADDIN_MODULE_GLOBAL_VARIABLE.HostApp.LanguageSettings.LanguageID[2] of
    1033: begin
    ...
  end;
end;

Localizing Outlook property pages

Property pages for the Tools | Options and Folder Properties dialogs are created every time when the dialogs are shown. To localize them, use the Load event of the property page class.

In Delphi, you use the OnCreate event exactly in the same way as shown above.

Localizing Excel task panes and Outlook forms

Add-in Express Excel task panes as well as Outlook forms are created whenever the application-specific task pane or form manager decides that the current context fits the form or pane settings. At this very moment, the constructor of the pane or form is called. That is, the localization code can be safely placed in their constructors. For instance,

    Public Sub New()
      MyBase.New()

      'This call is required by the Windows Form Designer.
      InitializeComponent()

      'Add any initialization after the InitializeComponent() call
      Dim LCID As Integer
      LCID = MyOutlookTodayAddin.AddinModule.CurrentInstance. _
         HostApplication.LanguageSettings. _
         LanguageID(Office.MsoAppLanguageID.msoLanguageIDUI)
      Select Case LCID
         Case 1033 'English
            Me.Text = "English Text"
         Case 1036 'French
            ...
         Case 1031 'German
            ...
         Case 1040 'Italian
            ...
         Case Else ' isn't supported - use English
            Me.Text = "English Text"
      End Select
   End Sub

In Add-in Express for Office and CodeGear VCL, you localize your Add-in Express Outlook forms and Excel task panes in the OnCreate event. To retrieve the current LCID, you use an appropriate manager. For instance, in an Add-in Express Outlook form, you do it as follows:

procedure TadxOlForm1.adxOlFormCreate(Sender: TObject);
var
LCID: Integer;
begin
  if (self.FormsManager <> nil) then begin
    LCID := self.FormsManager.OutlookAppObj.LanguageSettings.LanguageID[2];
  end;
end;

When using Add-in Express Excel task pane in Delphi, the same code may look like the following one:

procedure TadxExcelTaskPane1.adxExcelTaskPaneCreate(Sender: TObject);
var
LCID: Integer;
begin
  if (self.ExcelTaskPaneManager <> nil) then begin
    LCID :=
        self.ExcelTaskPaneManager.ExcelAppObj.LanguageSettings.LanguageID[2];
  end;
end;

Localizing Outlook Bar shortcuts and shortcut groups

Outlook Bar shortcuts and shortcut groups are created when the add-in starts for the first time. They are removed when the add-in is unchecked in the COM Add-ins dialog or the add-in is uninstalled. To localize them, you can use the same event and the same approach as shown above for the non-temporary command bar controls.

Andrei Smolin
Add-in Express Team Leader

In fact, there are 2 ways of customizing Outlook Today:

• It can be modified by the user, you just need to open Outlook help (see the Help menu) and enter “customize Outlook today” in the Search For field.
• Or, if you are a developer, you may want to add some functionality to Outlook Today programmatically. Let’s dig deeper into this.

Outlook Today is a set of HTML pages that use VBScript to display some Outlook-related information. If you open the Properties window for Personal Folder and navigate to the Home tab, you’ll see that the default page address is as follows:

res://C:\Program Files\Microsoft Office\OFFICE11\1033\outlwvw.dll/outlook4.htm

That is, the first Outlook Today page is shown from resources of some Outlook-related .DLL and this implies that no source code is available for Outlook Today.

On other words, the developer can only replace Outlook Today with a custom page. Let’s create such a page: open NotePad and copy / paste the text below:

<html>
<head>
<title>VBScript: the first try</title>
</head>
<body>
</body>

So, our custom page consists of the html tag that contains the head and body tags. The page is empty, as you can see. Now let’s add a button:

...
<body>
<input type="button" value="Go" onClick="greeting()"/>
</body>
...

The button caption is “Go” and when you click on the button, the greeting function is called. Now let’s add the function:

...
<head>
<script type="text/vbscript">

function greeting()
   document.write("<p>Hello, developer!</p>")
end function

</script>
</head>
...

This simple function prints a paragraph containing the greeting.

Now we are ready to plug the page into Outlook:

• Right-click on a folder and choose Properties in the context menu. Note that if the folder is Personal Folders, it means that we replace the Outlook Today page with our custom one.
• Specify the page location and tick the checkbox that shows the page.

Note that the Address textbox in the screenshot above corresponds to the WebViewUrl property of the MAPIFolder class (Folder in Outlook 2007). Accordingly, the checkbox labeled as “Show home page by default for this folder” corresponds to the WebViewOn property. These properties allow you to set an HTML page for any Outlook folder on the fly. For instance, you can replace the Outlook Today page with your custom one. If you use these properties, you should keep in mind that Outlook 2002 has a well-known bug confirmed by Microsoft: when you set WebViewUrl, the page will show up after the user switches to another folder, and then switches back to the folder with the home page (see http://support.microsoft.com/kb/305093 for details).

Here is the page:

At this stage, you can move in the following directions:

• Learning HTML

As always, Google is a good helper: just search for HTML Tutorial

• Learning VBScript

Here is a highly recommended guide: http://msdn2.microsoft.com/en-us/library/d1wf56tt.aspx

However, Outlook Today can display some information about tasks, e-mails / messages and appointments and meetings. To get these data as well as information about contacts, notes and other Outlook items, you have to dig into the Outlook object model:

• Open Outlook
• Choose Tools | Macros | Visual Basic Editor in the menu or just press Alt+F11
• In the VB IDE, choose View | Object Browser in the menu or just press F2

The object browser allows choosing the object model to browse in its topmost combo. Then you choose a class in the left pane and see class members in the right pane.

Application is the most important Outlook class. It provides the Session property of the NameSpace type. The NameSpace class contains Folders. Each folder (of the Folder type in Outlook 2007, MAPIFolder in Outlook 2000-2003) contains Items and other Folders. Each Item provides the Class property the value of which is a constant uniquely identifying every item type: MailItem, TaskItem, ContactItem, etc. To get help on a class or a class member just press F1. When reading help, pay attention to the availability and other aspects of using this or that class or class member in VBScript. For instance, Outlook events are not available in VBScript.

The following sample function uses the Outlook object model to demonstrate how you can apply the above-mentioned information. The function lists top-level folders in the current Outlook session:

function greeting()
   on error resume next

   dim OutlookApp
   on error resume next
   set OutlookApp = GetObject(, "Outlook.Application")
   if OutlookApp is Nothing then
      document.write("<p>Hello, developer!</p>")
      exit function
   else
      document.write("<p>Hello, Outlook developer!</p>")
   end if
   on error goto 0

   dim folderCount
   folderCount = OutlookApp.Session.Folders.Count
   document.write("<p>There are " & folderCount & " top-level folders in this session. ")
   document.write("Here they are:</p><ul>")
   for i = 1 to folderCount
      dim fldr
      set fldr = OutlookApp.Session.Folders.Item(i)
      document.write("<li>" & fldr.Name & "</li>")
   next
   document.write("</ul>")
   document.title = "VBScript: the first try"
end function

When I click the button, the function shows the following output in my Outlook 2003. You can do the same in Outlook 2000, 2002 (XP) and Outlook 2007:

As you can see, it is quite simple.

Add-in Express allows .NET developers to avoid such an extreme. It introduces the Advanced Outlook Form Regions technology, which among other features, empowers Outlook developers to quickly create custom forms / views in Outlook Today style.

Add-in Express provides a form class designed for deep integration with Outlook windowing: structures, chains, and procedures. To control the form, it supplies a special component, the Outlook Forms Manager. Let’s try this way.

In an Outlook COM add-in project, you add the above-mentioned form using the Add New Item dialog:

Then you add a Forms Manager to the Add-in module:

In the properties window, you choose the Forms property and add an item to the collection:

This item tells the Outlook Forms Manager to show the form specified in the FormClassName property when the user navigates to the folder specified in the FolderName property. The form will be shown as the home page for that folder: this is specified by the value of the ExplorerLayout property.

Here is how my custom Outlook Today form works in Outlook 2007. Please remember that you can achieve the same result in Outlook 2000, 2002 and Outlook 2003 :

And this way is a really simple and easy one! Note that you can debug your form in the same manner as you debug any .NET project: specify the external program to run and press F5. As to deploying the form, Add-in Express provides both MSI and ClickOnce ways.

Andrei Smolin
Add-in Express Team Leader

Hidden items in Extended MAPI

Storing some application-specific data between sessions is quite a usual task for Outlook developers. Such data are store either in the Windows registry or just in a file (binary or text, custom format or XML).

The MAPI subsystem provides yet another possibility: it allows you to create and save any data in hidden items. As the name suggests, a hidden item isn’t visible in Outlook. Hidden items are similar to usual mail, contact, and task items because they have the same properties: subject, body, attachments, etc. Also, you can find the term “associated content” in various information sources which has exactly the same meanings.

As an example of this approach, Outlook saves folder view settings in hidden items. Views, custom form definitions, archive settings, and many other configuration options can be stored in such hidden items. In Outlook 2007, you can find the StorageItem class that describes a hidden item.

MAPI Store Accessor provides an easy access to this feature of MAPI through the HiddenMapiItems property of the AddinExpress.MAPI.Folder class. To demonstrate the use of this property, I developed a small application that creates a new MAPI session for the default MAPI profile and show the following form:

The form allows choosing a folder name in order to see its hidden items. In the list box, I show the subject and the class name of hidden items. You can download the source code of the Hidden Outlook Items via Extended MAPI sample in VB.NET and in C#.

You can create such an item and use standard and / or custom properties to store your data.

To set a value of some standard property in the SetProperty method, you use the corresponding property tag from the AddinExpress.MAPI.ADXMAPIPropertyTag enumeration.

To create a custom property you have to combine a property type with a property ID into the property tag. For example, consider the following code:

C#:

mapiItem.SetProperty(0x340F0003, myLongValue);

VB.NET:

mapiItem.SetProperty(CType(&H340F0003, UInteger), myLongValue)

The first parameter of the SetProperty method is a property tag. The first part of the property tag is a property ID (0×340F) and the second one is a property type. In this case the property type is PT_LONG (0×0003).

Extended MAPI allows you to choose an ID for your custom property from the predefined ranges of values. The ranges are listed in the MAPITags.h file. Here they are:

The following ranges should be used for all property IDs. Note that property IDs for objects other than messages and recipients should all fall in the range 0×3000 to 0×3FFF:

The 3000-3FFF range is further subdivided as follows:

Find more about MAPI property tags on MSDN.

Eugene Astafiev
Add-in Express Team

You can easily imagine how often the Add-in Express support team type the same words or phrases in their e-mails hundreds of time, explain the same things again and again to our customers and prospects: greetings, signatures, the same answers to the same questions about ordering, downloading, installing, activating, and using our products, etc.

Probably you need to do the same in your daily work. Of course, you can use signatures in Outlook, but it is not convenient if you have more than 10-15 of them.

The idea was born when we realized that we spent too much time on inserting standard phrases into our e-mails. Aren’t we Office developers? Didn’t we develop Add-in Express for building Office add-ins in .NET, Outlook, Excel and Word plug-ins in VSTO, and Office COM add-ins in Delphi. Didn’t we develop the Add-in Express Extensions for Outlook that allows embedding custom forms into Outlook windows? When we detected the problem and found the way to solve it, the life speeded up – you know how this happens.

Here is the result of our work.

The form embedded to the right side of the e-mail window above is a warehouse of phrases and blocks of text I use in my daily work. The screenshot above shows how you can organize your phrases in a folder tree. If you double-click the caption of the phrase template, the add-in pastes the phrase to where the text cursor stands in your e-mail. The add-in UI allows you to resize the form using the splitter. You can also use the button on the splitter to collapse / expand the form.

Now let’s create a sample COM add-in project to show a form like the one above.

You create a new Outlook COM add-in by choosing the Add-in Express COM Add-in project template in the New Project dialog in Visual Studio 2003 - 2008 or in the File | New | Other dialog in Delphi. VSTO developers create a COM add-in project and add an Add-in Express COM Add-in Module to the project via the Add New Item dialog.

The plug-in will display a form embedded into Outlook windows. To create such a form, you follow two steps below:
1. Add a new Outlook Form to your project and populate it with controls
2. Add Outlook Forms Manager to the add-in module, create an item in the Forms collection of the Forms Manager, choose the form the item controls, and specify context and UI properties for the form.

To create the form itself, you choose the Add-in Express Outlook Form item in the appropriate dialog of your development platform:

• For Add-in Express .NET projects, in the Add New Item dialog, you choose the Common Items / Add-in Express Items / Outlook / Add-in Express Outlook Form item
• For Add-in Express VSTO projects, in the Add New Item dialog, you choose the Common Items / Add-in Express for VSTO Items / Outlook / Add-in Express Outlook Form item
• In Add-in Express VCL projects, you choose the Add-in Express Outlook Form item in the File |New | Other dialog.

The form is a special descendant of System.Windows.Forms.Form (in Delphi, TForm). It provides a number of properties. In our Outlook plug-in, we will use the InspectorObj property. It returns the Outlook.Inspector COM object for the e-mail window that the form is shown in. Using this object, you can implement the most important functionality provided by the plug-in: pasting a string at the cursor location in the current message body.

To understand the scale of the problem, it’s enough to admit that Outlook shows the following e-mail inspector window types:

• Word
• HTML
• Plain text
• RTF

However, for the add-in that inserts text strings into the message, the last one, RTF, doesn’t make sense because Outlook uses this format to read (not edit) e-mail messages.

To recognize the message format, you can use the Inspector.EditorType property. Then, you work with the message text using the following routes:

Note also that when you use Outlook Templates plug-in to paste a phrase, the add-in returns focus to the editor window and enables the Edit | Undo menu item without faults. “I love this game”.

A notable part of the form is the toolbar at its top. To create such a toolbar, you can use built-in and third party controls. For more ideas, have a look at how to paint toolbar controls in the Office style.

Other tasty features of the plug-in are the result of usual developer’s work:

Enough with the form. Now we need to add an Outlook Forms Manager to the add-in module, add an item to its Items collection, and specify the item’s settings. We know that the form must be located on the right side of the mail inspector window. Here are the item’s properties to set:

That’s all for now. Hope you find it useful and enjoy using the Template Phrases for Outlook as I do.

Andrei Smolin
Add-in Express Team Leader

For example, imagine the following situation: you develop an add-in which shows some data from a database. For this task, standard Office controls are practically useless, because their number is limited: button and combo box. Besides the obvious fact that such controls don’t fit for the task, they are toolbar controls and you can use them on Office toolbars only. Isn’t it better to show data using data presentation controls, such as DataView, ComboBox, TextBox, RichTextbox, etc designed specially for this purpose? You can show them in separate forms, on custom task panes in Office 2007, on toolbars, and on pre-Office 2007 panes. BTW, Add-in Express .NET and Add-in Express for VSTO allows you to place .NET controls onto Office toolbars, create custom task panes in Excel 2000 – 2007, Advanced Form Regions for Outlook 2007 - 2000.

But you know that look-n-feel of these controls differ from standard Office controls. How to cope with this? Remember the rule of thumb: if you can’t do something with ready-to-use components, customize them! As a .NET developer you can inherit any existing control and add your own logic to it. That is the right way. Let’s follow it.

To make your controls comply with Office styles, you should know how Office paints its controls.

Microsoft Office 2000

The color scheme of the MS Office 2000 is almost completely based on colors of the operating system. Just change a system color, and Office 2000 will reflect this change without any unexpected mismatches. To search for Office colors, you use the PrintScreen button and any graphic editor which is able to determine RGB components of a pixel. For instance, you can use Paint.NET. Using this or some other graphic editor you can study every detail of a command bar control (which is an essence of pre-Ribbon coloring approaches) or any other area of all Office applications.

Microsoft Office 2002 & 2003

Some colors in Office 2002 and 2003 are identical to system colors but others look like computed using a combination of system colors. Unfortunately, I am not good at guessing them. And you?

.NET Framework 2.0 provides two classes to help you in searching Office colors:

System.Windows.Forms.ProfessionalColorTable
System.Windows.Forms.ProfessionalColors

These classes allow your colors to approach (no more than that) to Office colors. All Office 2003 applications have color gradients – vertical and horizontal – in toolbars and toolbar controls. These classes give you the beginning, middle and ending colors of Office gradients.

Microsoft Office 2007

Microsoft presented a new GUI – Ribbon, also known as Fluent UI. Only the following Office applications use this new GUI:

• Word
• Excel
• PowerPoint
• Outlook (except for the Explorer window)
• Access

Others use the traditional command bar model. The color scheme of Microsoft Office 2007 isn’t based on Windows system colors. Instead, all Office 2007 applications use three predefined schemes:

• Black
• Blue
• Silver

To switch between them, you use the Options menu in any Office application that uses the Ribbon UI.

Add-in Express provides the OfficeColorSchemeChanged event that allows tracking changes in the color scheme. The second parameter in the event handler is of the AddinExpress.MSO.OfficeColorScheme type. To get the current color scheme, you use the OfficeColorScheme property. Believe me, this part is an easy one.

High contrast mode

This mode is used in the operating system to improve readability. To turn this mode on or off, you can use “Alt + Shift + PrtScr” shortcut (left Alt and Shift buttons only) or use settings in the Control Panel. To find out whether the user has enabled the high-contrast mode you need to check the following static property:

System.Windows.Forms.SystemInformation.HighContrast

In the System.Windows.Forms.SystemInformation (supported in all versions of the .NET platform), you can find a lot of useful information about system settings such as current GUI settings of the OS and such.

Changing color schemes

When the user changes the system color settings, Windows notifies all windows on the system. In .NET, you can subscribe to the UserPreferenceChanged event of the SystemEvents class. Consider the following code:

[VB.NET]
AddHandler Microsoft.Win32.SystemEvents.UserPreferenceChanged, _
   AddressOf SystemSettingsChanged

....

Private Sub SystemSettingsChanged(ByVal sender As System.Object, _
   ByVal e As Microsoft.Win32.UserPreferenceChangedEventArgs)
   If (e.Category = Microsoft.Win32.UserPreferenceCategory.General) Then
      '
   End If
End Sub

[C#]
Microsoft.Win32.SystemEvents.UserPreferenceChanged +=
new Microsoft.Win32.UserPreferenceChangedEventHandler(
         SystemEvents_UserPreferenceChanged);

...

void SystemEvents_UserPreferenceChanged(object sender,
   Microsoft.Win32.UserPreferenceChangedEventArgs e)
   {
      if (e.Category == Microsoft.Win32.UserPreferenceCategory.General)
      {
         //
      }
   }

In the event handler, you choose new colors and update your custom control view.

Gradients and fonts

As you can see, Office 2003 and 2007 toolbars are filled with a gradient. Note, however, that the gradient may differ depending on the position of the command bar: horizontal, vertical, and floating

When customizing .NET controls, remember about fonts. Office toolbars’ fonts are based on system fonts listed in System.Drawing.SystemFonts. You can use UserPreferenceChanged to track one or several system fonts that Office controls depend on (you have to determine this yourself). To apply a font to your controls, you have to use the System.Drawing namespace.

Eugene Astafiev
Add-in Express Team

Say, if the event handler for your Office 2007 Ribbon button is called MyEventHandler, the XML must contain this name in the following way:

<customui xmlns="http://schemas.microsoft.com/office/2006/01/customui">
  <ribbon>
    <tabs>
      <tab idMso="MyTab">
        <group id="MyGroup" label="My Group">
          <button id="button1"
                    size="large"
                    label="My Button"
                    screentip="My Button Screentip"
                    onAction="MyEventHandler"
                    imageMso="HappyFace" />
        </group>
      </tab>
    </tabs>
</customui>

The only way to make sure that the XML above is correct is to run your add-in. That is, you can’t check if your XML is valid at design-time. All my life I have been told that run-time warnings cost more than compile-time ones. Haven’t you?

There is another source of troubles: the signature of the method should conform to the rules described in manuals (see Downloads in the end of this post). However, if the signature of your method doesn’t correspond to that required by the Office 2007 Ribbon (say, if you add an extra parameter, mistakenly, of course), you’ll be never informed about this and your event handler will never be called. Nice, isn’t it?

These error-prone and time-consuming issues are successfully resolved in Add-in Express 2007 by introducing the Office 2007 Ribbon tab designer.

With this Ribbon tab designer, you never have to deal with XML. Instead, you create the UI right in the designer that generates appropriate Ribbon components, events of which are handled in the usual manner.

For instance, let’s create a custom group with a custom Ribbon button on a custom tab in Excel 2007:

Now we handle the Click event of the button:

After that re-target the group to the TabHome built-in tab:

That’s easy. However, the potential of our approach to the Office 2007 Ribbon UI customization becomes even more evident now, when Visual Studio 2008 includes the Ribbon designer for its VSTO 3 projects. Note that VSTO 3 is integrated with VS 2008; it provides project templates in the Office Visual Basic / Office and Visual C# / Office nodes of the New Project dialog in Visual Studio 2008.

To start with, Add-in Express 2008 for Office and .NET supports all Microsoft Office versions and, accordingly, you needn’t have several code bases for different Office versions. Instead, you create just one project that works for all Office versions. That is, you can just use the Ribbon visual designer in your project and the corresponding Ribbon XML markup will be generated, verified and transferred to Office 2007 with no extra steps from you part. I’m sure, the last feature is exactly what any developer would expect from the designer. But this isn’t the case with the Visual Studio 2008 designer. It is available for projects targeting Office 2007 only. I don’t like to speculate on why Microsoft chooses this or that way. Nevertheless, the fact is that if you need to support both Office 2003 and 2007, you need to create two VSTO projects: one for Office 2003 and another one for Office 2007.

Now I want to compare both Ribbon designers: Add-in Express’ and VSTO’s. Let me be honest and start from flaws in the Add-in Express Ribbon tab designer. Currently, I see two of them: first, our Office 2007 Ribbon tab designer allows designing a single tab only and second, it has a design-time defect in drawing items of a list, combo, and gallery. On the other hand, Microsoft’s designer supports designing many tabs and hopefully they display every tiny thing in their designer correctly.

Both designers provide quite similar features: you can design and handle any custom Ribbon controls: button groups, buttons, list boxes, combo boxes etc. You can target any control to a built-in or custom tab. Both Add-in Express and VSTO 3 generate XML from their designers transparently.

The most evident distinction between designers lies on the surface, however. In VSTO, the designer is just a designer. While in Add-in Express, the designer is part of the component set purposed for constructing the UI of your Office 2007 add-in. Let’s take built-in Ribbon controls. Neither of the designers allows you to process a built-in ribbon control. But Add-in Express provides a special component, RibbonCommand that allows connecting to any built-in ribbon control and handling its events without the need to dig into XML.

For instance, see how to disable the Copy command in Word 2007.

As to VSTO 3, it includes the Ribbon (XML) item available in the Add New Item dialog (for projects targeting Office 2007 only). This approach adds some more flies to the ointment; just read comments in the file created when the Ribbon (XML) item is run:

• Copy a code block to this or that class
• Create callbacks and note some special case
• Add callback names to appropriate attributes of appropriate control tags in the XML file.

R-r-r-r! :)

Here, at Add-in Express we are working on simplifying and speeding up the development of Office COM add-ins. That’s why Add-in Express Ribbon UI designer gives you the possibility to share Ribbon controls across multiple add-ins. Note that this requires manual operations in VSTO 3.

Here is the source code that creates the above mentioned Ribbon components (Ribbon tab that contains a ribbon group containing a ribbon button). Note that the tab is shown only when the user composes or edits an e-mail in Outlook 2007.

[VB.NET code]

Private Sub InitializeComponent()
   Me.components = New System.ComponentModel.Container
   Dim resources As System.ComponentModel.ComponentResourceManager =
New System.ComponentModel.ComponentResourceManager(GetType(AddinModule))
   Me.RibbonTab = New AddinExpress.MSO.ADXRibbonTab(Me.components)
   Me.RibbonGroup = New AddinExpress.MSO.ADXRibbonGroup(Me.components)
   Me.RibbonButton = New AddinExpress.MSO.ADXRibbonButton(Me.components)
   Me.ImageList1 = New System.Windows.Forms.ImageList(Me.components)
   '
   'RibbonTab
   '
   Me.RibbonTab.Caption = "My Ribbon Tab"
   Me.RibbonTab.Controls.Add(Me.RibbonGroup)
   Me.RibbonTab.Id = "adxRibbonTab_33d6c3f63d17474db7bc3a04e1b1e7d9"
   Me.RibbonTab.Ribbons = AddinExpress.MSO.ADXRibbons.msrOutlookMailCompose
   '
   'RibbonGroup
   '
   Me.RibbonGroup.Caption = "My Ribbon Group"
   Me.RibbonGroup.Controls.Add(Me.RibbonButton)
   Me.RibbonGroup.Id = "adxRibbonGroup_65d7dab572ef41f7b462701d5210256c"
   Me.RibbonGroup.Ribbons = AddinExpress.MSO.ADXRibbons.msrOutlookMailCompose
   '
   'RibbonButton
   '
   Me.RibbonButton.Caption = "My Ribbon Button"
   Me.RibbonButton.Id = "adxRibbonButton_8257f64d29104b11a37ceb4b65f69359"
   Me.RibbonButton.Image = 0
   Me.RibbonButton.ImageTransparentColor = System.Drawing.Color.Transparent
   Me.RibbonButton.Ribbons = AddinExpress.MSO.ADXRibbons.msrOutlookMailCompose
   Me.RibbonButton.Size = AddinExpress.MSO.ADXRibbonXControlSize.Large
   '
   'ImageList1
   '
   Me.ImageList1.ImageStream = CType(resources.GetObject("ImageList1.ImageStream"),
System.Windows.Forms.ImageListStreamer)
   Me.ImageList1.TransparentColor = System.Drawing.Color.Transparent
   Me.ImageList1.Images.SetKeyName(0, "account_actions_24.png")
   '
   'AddinModule
   '
   Me.AddinName = "MyAddin7"
   Me.Images = Me.ImageList1
   Me.SupportedApps = AddinExpress.MSO.ADXOfficeHostApp.ohaOutlook

End Sub

[C# code]

private void InitializeComponent()
{
   this.components = new System.ComponentModel.Container();
   System.ComponentModel.ComponentResourceManager resources =
 new System.ComponentModel.ComponentResourceManager(typeof(AddinModule));
   this.RibbonTab = new AddinExpress.MSO.ADXRibbonTab(this.components);
   this.RibbonGroup = new AddinExpress.MSO.ADXRibbonGroup(this.components);
   this.RibbonButton = new AddinExpress.MSO.ADXRibbonButton(this.components);
   this.imageList1 = new System.Windows.Forms.ImageList(this.components);
   //
   // RibbonTab
   //
   this.RibbonTab.Caption = "My Ribbon Tab";
   this.RibbonTab.Controls.Add(this.RibbonGroup);
   this.RibbonTab.Id = "adxRibbonTab_04dee6e0f08a4f8fa31f0f5982a998c7";
   this.RibbonTab.Ribbons = AddinExpress.MSO.ADXRibbons.msrOutlookMailCompose;
   //
   // RibbonGroup
   //
   this.RibbonGroup.Caption = "My Ribbon Group";
   this.RibbonGroup.Controls.Add(this.RibbonButton);
   this.RibbonGroup.Id = "adxRibbonGroup_74cbaba4b40444e6b45f1b8d9570410d";
   this.RibbonGroup.Ribbons = AddinExpress.MSO.ADXRibbons.msrOutlookMailCompose;
   //
   // RibbonButton
   //
   this.RibbonButton.Caption = "My Ribbon Button";
   this.RibbonButton.Id = "adxRibbonButton_6f220d15d7824b048e09e627e77f4227";
   this.RibbonButton.Image = 0;
   this.RibbonButton.ImageTransparentColor = System.Drawing.Color.Transparent;
   this.RibbonButton.Ribbons = AddinExpress.MSO.ADXRibbons.msrOutlookMailCompose;
   this.RibbonButton.Size = AddinExpress.MSO.ADXRibbonXControlSize.Large;
   //
   // imageList1
   //
   this.imageList1.ImageStream = ((System.Windows.Forms.ImageListStreamer)
(resources.GetObject("imageList1.ImageStream")));
   this.imageList1.TransparentColor = System.Drawing.Color.Transparent;
   this.imageList1.Images.SetKeyName(0, "account_actions_24.png");
   //
   // AddinModule
   //
   this.AddinName = "MyAddin8";
   this.Images = this.imageList1;
   this.SupportedApps = AddinExpress.MSO.ADXOfficeHostApp.ohaOutlook;

}

Andrei Smolin
Add-in Express Team Leader

Related posts:

Customize Office toolbars, ribbons, task panes on RO Chrome
Create Office add-ins: ribbons, toolbars, task panes, menus

Let’s run Internet Explorer version 6 or 7. Now run Windows Task Manager and go to the Processes tab, find the IE process. You see that you have one running process of Internet Explorer. Run a new instance of Internet Explorer using a shortcut or typing “iexplore” in the Run menu of the Start button. And have a look at Task Manager again. Now you see that you have two different IE processes running on your machine. In other words, you have two windows of Internet Explorer in different processes.

Close either of the IE windows and press “Ctrl+N” in the other. Check up Task Manager again. Now you see that you have one running IE process. But you have two IE windows. Interesting, isn’t it? The point is that you opened a new frame of Internet Explorer, but not a new instance. IE 7 behaves in the same manner. Let’s make sure. Click on the “New Tab” button to create a new tab or use the “Ctrl+T” shortcut. Check Task Manager for IE processes. You see that you still have one IE process. Naturally, each tab and window is created in a separate thread of execution. What is more, a new instance of your IE add-on is created for every such tab.

With Add-in Express you have a few ways to communicate with various add-on instances.

Communicating with IE add-ons in the same process

In Add-in Express, an IE module corresponds to the Internet Explorer add-on. That is, to access another instance or instances of the add-on, you need to find the corresponding IE modules. Then you can access the page and browser window (frame) using the appropriate properties of the module.

Every IE thread has its own ID – Thread ID (see the ThreadId property of the module). Using the thread ID you can easily get the module instance of your IE plug-in. Having the module object you can do various things on your own. Consider the following code in the class definition of the module:

int threadId = this.ThreadID;
AddinExpress.IE.ADXIEModule module = this.GetModuleByThread(threadId);

You can also get the module by index in the collection:

int threadId = this.GetModuleIndex();
AddinExpress.IE.ADXIEModule module = this.GetModuleByIndex(threadId);

Please note that using the thread id you can avoid the non-existing index error. For example, you’ve closed a tab and are trying to get the module by index which you saved earlier. You will have an exception, because there isn’t such an index in the collection.

To get the module, you can also use the CurrentInstance property that returns a System.Collections.SortedList collection:

System.Collections.SortedList listOfModules=
AddinExpress.IE.ADXIEModule.CurrentInstance;

The key in the collection is a thread ID of the add-on. But this collection is not thread-safe, so you’d better use GetModuleByThread and GetModuleByIndex.

Communicating with IE add-ons in different processes

In this case, you can’t get a module using GetModuleByThread and GetModuleByIndex, because the modules you need to access are located in another process. But you can use windows messages to communicate between processes. Fortunately, the IE the module contains methods for this task. First, you need to specify message Id constants that identify your messages. For example, consider the following code:

// declare the following constants at the module level
private static int WM_USER = 0x0400;
private static int WM_EXAMPLE = WM_USER+1000;
...
// add an event handler to the OnSendMessage event
private void IEModule_OnSendMessage(AddinExpress.IE.ADXIESendMessageEventArgs e)
      {
         if (e.Message == WM_EXAMPLE)
         {
            System.Windows.Forms.MessageBox.Show(this.ThreadID.ToString());
         }
      }

When you call one of the SendMessage methods provided by the IE module, the method generates a windows message and puts it to the message queue of the corresponding window. When OS permits, the message will be processed and the IE module will generate the OnSendMessage event. The code above produces a message box for each IE module that is run on the PC.

There are some forms of SendMessage methods:

 -  public void SendMessage(int message, IntPtr wParam, IntPtr lParam);

It sends a custom message to the internal window of Internet Explorer. When the message is received, the Add-in Module raises the OnSendMessage event.

 -  public void SendMessageToAll(int message, IntPtr wParam, IntPtr lParam);

It sends a custom message to the all windows of Internet Explorer. When the message is received, the Add-in Module raises the OnSendMessage event.

 -  public void SendMessageToInstance(IntPtr nativeHandle, int message, IntPtr wParam, IntPtr lParam);

Sends a custom message to the specified window of IE. When the message is received, the Add-in Module raises the OnSendMessage event.

Which of the above methods to use? It depends. When I was programming the Advanced Search for Internet Explorer plug-in I had to report to other add-on instances that the current instance (the current thread of execution, which may be a tab or a window) was closing in order to update the Search Results tree. The solution is to use the SendMessageToAll method and the OnSendMessage event handler. It is a non-trivial event for IE add-ons, to trigger which you need to call one of the functions specified above. To handle this event you just need to monitor the id of the message in the OnSendMessage event handler of the add-on module.

Tips on how to program IE plug-ins

To show a tab. Sometimes you need to activate a tab in an IE window. For example, in the Advanced Search add-on, when you press on the tree node to highlight the found element, you are taken to the tab that the element belongs to. In this case, the add-in finds the module of the tab that should be activated, and calls the TabActivate method that activates the tab.

To show an IE toolbar programmatically. Let’s assume that you added a toolbar item to the IE add-on project and named it “MyIEToolBar1” .The following code shows / hides the toolbar. In particular, you can use such code, for example, in the event handler of your custom keyboard shortcut.

     // getting the add-on module by thread ID
     IEModule module = AddinExpress.IE.ADXIEModule.CurrentInstance[this.ThreadID] as IEModule;
            if (module != null)
            {
		 // getting the toolbar type
                Type t = typeof(MyIEToolBar1);
                int index = module.ToolBars.IndexOf(t.FullName);
                if (index >= 0)
                {
		     // getting an instace of the toolbar by index
                    AddinExpress.IE.ADXIEToolBarItem item = module.ToolBars[index];
                    object g = t.GUID.ToString("B");
                    object dummy = null;
                    if (item.ToolBarObj == null)
                    {
                        object bShow = true;
		         // showing the IE toolbar
                        IEApp.ShowBrowserBar(ref g, ref bShow, ref dummy);
                    }
                    else
                    {
                        MyIEToolBar1 dm = item.ToolBarObj as MyIEToolBar1;
                        if (dm != null)
                        {
                            if (!dm.Visible)
                            {
                                object bShow = true;
				  // showing the IE toolbar
                                IEApp.ShowBrowserBar(ref g, ref bShow, ref dummy);
                            }
                            else
                            {
                                object bShow = false;
			          // hiding the IE toolbar
                                IEApp.ShowBrowserBar(ref g, ref bShow, ref dummy);
                            }
                        }
                    }
                }
     }

It’s easy to change the code above in order to show / hide an IE bar: you just need to replace the types of the module and toolbar / bar with those that you have in your add-on. Also use the Bars collection instead of Toolbars.

All the sources above belong to the Advanced Search for Internet Explorer (you can download it here) and to other samples distributed with Add-in Express for Internet Explorer.

Eugene Astafiev
Add-in Express Team

If you google for “Error 2908″, you’ll find out that this error occurs for a number of applications. Workarounds exist for installing Office 2000 on Windows 98 or ME, NET Framework 1.1, Visual Studio 2005. But none of those workarounds worked for us.

Then we found an interesting post on the www.eggheadcafe.com forum: they added Crystal Reports merge modules to their setup and got this error. This resulted in “reinstalling windows on computers affected with this error.” What Microsoft suggested is “ask Business Objects company that produces the Crystal Report for assistance”. As you may assume, Crystal Reports supporters sent poor devils back to Microsoft.

However, we googled out some vague notes that the cause of this error may relate to the number of files included into the package. This was somehow backed up by Orca that reported the following incomprehensible warning message: Feature ‘DefaultFeature’ has XXXX components. This could cause problems on Win9X systems. You should try to have fewer than 817 components per feature.

To verify this assumption, we created a simple setup with some 2000 files. Nevertheless, this setup program has run through the install/uninstall/install procedure successfully. But when we added a custom action (Install, Rollback, and Uninstall), we got Error 2098 again. Moreover, it turned out that install/uninstall is enough for breaking the Windows Installer down. Then we found that the number of files that does the trick lies between 1000 and 1022. We don’t know if this number depends on the number of custom actions.

This research forced us to decrease the number of Add-in Express files by moving demo projects to a ZIP archive. And in this way, we overpowered Error 2908.

But this was not the end of the story. We felt obliged to find a way for our customers to restore their PCs if they have got into this trap by installing Add-in Express.

The solution was found by a pure chance. Thank Heavens.

Deleting the following key restores the functionality of the Windows Installer:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
Installer\UserData\S-1-5-21-1123561945-1935655697-1060284298-1003\
Components\AD95649F068525549B26938D7D18FEA7

We don’t know who created this key: repairing Office and all .NET Framework versions on that PC doesn’t restore the key. Currently, we believe this key is created by Visual Studio 2008 Beta 2. We don’t know what impact the deletion of this key may have on any software on that PC.

What makes us think the key is suspicious? The registry contains the following branches:

Further on, I will refer to branch S-1-5-18 as ShortSID and S-1-5-21-1409082233-343818398-725345543-1004 as LongSID.

Our experiments showed that products installed for all users fall into the ShortSID/Products branch. Accordingly, products installed for the current user only, fall into the LongSID/Products branch. For every file in the setup project, we got an entry in the Components branch. This entry contains a registry value whose name refers to the product’s entry in the Products branch. Hope this makes sense :)

The key mentioned above looks suspicious for the following reasons:
Firstly, it is located in the LongSID/Components branch (the registry value is (B3414A45B4B628042B8446B35265C1BC), but, in the LongSID/Products branch, there is no corresponding product.

Secondly, the value of this registry value contains a question mark instead of a colon in the path: C?\WINDOWS\system32\rgb9rast_2.dll

We tried deleting this key and it helped. Finally, we tried creating this key on a clean PC and reproduced Error 2908 with our test setup project.

Conclusions:
1. It required 3 days X 4 developers to fix the problem that, as we know for sure, was not engendered by us.
2. Any developer can create a setup project that may make Windows practically inoperable.
3. This developer will be blamed for no reasons.

To get rid of such security warning messages, use the Outlook Security Manager that effectively disables / enables the Outlook Security. With the ActiveX edition of this product you can easily switch the Outlook security off and on. Here we describe two methods of sending emails in Microsoft Access using the ActiveX edition of Outlook Security Manager.

Sending emails using the DoCmd. SendObject method

With the ActiveX edition of Outlook Security Manager you write the following simple code:

Sub SendEmailMessageViaDoCmd()
Dim SecurityManager As Object
  Set SecurityManager = CreateObject("AddInExpress.OutlookSecurityManager")
  SecurityManager.DisableSMAPIWarnings = True
  On Error GoTo Finally
  DoCmd.SendObject acSendNoObject, , ,"user@server.com", , , _
  "Message subject", "Message body", False
Finally:
  SecurityManager.DisableSMAPIWarnings = False
  Set SecurityManager = Nothing
End Sub

What does this procedure do?

At first, the Outlook Security Manager object is declared and created. Then DisableSMAPIWarnings of this object is set to true. At this moment the Outlook Security Manager disables security warnings from the so-called Simple MAPI email processing protocol, which is used whenever an email is being sent. Then your familiar DoCmd creates and sends your e-mail. And finally, DisableSMAPIWarnings is set to False, enabling security warnings from Simple MAPI. Note, this last step is important, because if you fail to re-enable the Simple MAPI Security, some other MDB or ADP opened in this MS Access session can potentially do some harm to you.

Sending emails using Outlook Object Model

With the ActiveX edition of Outlook Security Manager you send emails in the following way:

Sub SendEmailMessageViaOutlookObjectModel()
Dim olApp As Outlook.Application
  Set olApp = New Outlook.Application 'GetObject(,"Outlook.Application")
Dim email As Outlook.MailItem
  Set email = olApp.CreateItem(olMailItem)

Dim SecurityManager As Object
  Set SecurityManager = CreateObject("AddInExpress.OutlookSecurityManager")
  SecurityManager.ConnectTo olApp
  SecurityManager.DisableOOMWarnings = True
  On Error GoTo Finally
  email.Recipients.Add "user@server.com"
  email.Subject = "Message subject"
  email.Body = "Message body"
  email.Send
Finally:
  SecurityManager.DisableOOMWarnings = False
  Set SecurityManager = Nothing
  Set email = Nothing
  Set olApp = Nothing
End Sub

How does this procedure work?

First off, you get the Outlook.Application object and the MailItem object (the last one represents an email in Outlook). Then you create the Outlook Security Manager object and connect it to the Outlook application. Then the DisableOOMWarnings of the Outlook Security object is set to true. The ‘OOM’ part in the property name stands for “Outlook Object Model”. At this moment the Outlook Security Manager disables Outlook Security prompts. Then you set the email properties, such as, Subject, Body, add email addresses to the Recipients collection and send the email. And finally, DisableOOMWarnings is set to False, enabling Outlook Security. Note, this last step is highly important, because in the other case you can leave your Outlook unprotected from really malicious software. Sure, it is not what you really want. That’s all for now. Hope this helps.

Andrei Smolin
Add-in Express Team Leader

Related posts:

Why Outlook is not closing when I run my add-in?

For the .NET developer, Office add-ins are class libraries implementing the IDTExtensibility2 COM interface and registered in an appropriate registry branch in HKEY_CURRENT_USER. To run for all users on the current PC, Office COM add-ins must be registered in HKEY_LOCAL_MACHINE. Obviously, this requires administrative privileges.

A number of other COM interfaces require implementation if your add-in customizes the Office 2007 Ribbon user interface (IRibbonExtesibility), creates custom task panes (ICustomTaskPaneConsumer), and so on. The user is allowed to enable or disable COM add-ins via COM Add-ins dialog:

How to start writing add-ins for Microsoft Office? What problems should you be aware of? How do you deploy the add-in? What tools are available?

Is it possible to write an Office add-in that will fulfill my task?

First off, you are to find out if the Office application you want to use as a host for your add-in provides the features you need. Here is one of the most frequently asked questions on the Add-in Express forum: Is it possible to add a custom page to the Tools | Options dialog in Excel? Our standard answer is: It is not possible because the Excel Object Model doesn’t provide any way for this.

However, where does an object model live? The best way to study any Office Object model is the Object browser available in the Visual Basic IDE. Having run the host application, you open the environment by choosing the Tools / Macro / Visual Basic Editor menu item or by pressing Alt + F11. Note that some Office applications, recent ones mainly, do not provide IDE. If it is the case, please refer to Programmer’s Reference or MSDN.

When in the IDE, you choose View / Object Browser in the menu or press F2. The Object Browser provides you with public classes, their properties and methods as well as with public enumerations for all object models that the currently open document refers to (use Tools | References to add a new reference). You can restrict the browser to show the public interfaces of a single object model: use the topmost combo to select, say Outlook, Word, Excel, or MSProject. The Object browser allows searching through any or all object models. There is a restriction though: it doesn’t search through a method’s parameters. When you find an object of interest, you click it and press F1 to get the help article related to this object. Those help articles are the shortest way to understanding of the object model.

The Object Browser reveals all the declarations in VBA syntax. If you have no or little experience in VB6 (VBA) programming, please note that some declarations don’t specify the types of parameters and/or return values. Consider the following declaration in the Word object model – note that this pattern is often used in other object models:

Function Item(Index) As Bookmark

It defines the Item function which returns a value of the Bookmark type. However, the declaration doesn’t reveal the type of the Index parameter. In such situations you should know that the Browser omits the Variant keyword. That is, the declaration above should read as follows:

Function Item(Index as Variant) As Bookmark

The Variant data type is a predecessor of the Object data type in .NET programming. Like Object variables, Variant variables can accept almost any data types. When you click the function above and press F1, it appears that the Index parameter can accept numeric and string values – either the index position of the Bookmark in the Bookmarks collection or a bookmark’s name.

I understand that you may never have used (and will probably never use) VBA. However, I insist on using the Object Browser: it is the essential step of getting into the insight of the Object Model of any Office application.

To understand user interface options, you select Office in the topmost combo of the Object Browser. Here you find definitions of the types that all Office applications share: COM add-ins, command bars and controls, custom task panes, ribbons, etc.

What are the typical problems with Office add-ins?

If you’ve never done Office development before, you’ll be in a shock because while the user’s side of any Office application is remarkably stable and robust, the application’s object model is a completely different story. It’s like a minefield of bugs and issues: command bars behave differently in different Office applications or become disconnected suddenly, Outlook hangs in the Task Manager or doesn’t fire the events you rely upon, Office updates change the sequence of events, and many, many more. All this stuff increases the debugging time considerably.

Many problems arise on the .NET – COM interaction area because .NET and COM differ in their strategies of object releasing. Blogs and newsgroups have a great number of questions like “Why Outlook is not closing?“. The problem has its name: Releasing COM objects in .NET. When releasing COM objects in a stand-alone .NET application, you are free to use any of the three approaches discussed by Andrew Whitechapel. Please note, these approaches are applied to standalone applications but not to add-ins. I’ll try to prepare some add-ins demonstrating the problems with using the approaches described in Andrew Whitechapel’s book. To make a long story short, COM add-ins developers have the only way. I’d call it the Bee Way: whenever you get a reference to a COM object, you must release it using the Marshal.ReleaseComObject method. You may think this will bloat your code sufficiently. However, this is the right way: you keep every aspect of your add-in under control. Here, at Add-in Express, we have a saying: Office overlooks mistakes for a very short period only.

Add-in deployment

The crucial question is: who will install your add-in? There are two possible answers: an admin or a standard user. If the admin installs your add-in, you have no problems when, say, your add-in requires to install its prerequisites. Note that some prerequisites are absolute musts: .NET Framework :), Windows Installer 3.1, Shared Add-in Support Update for Microsoft .NET Framework 2.0 (KB908002).

However, administrators are not inclined to participate in the add-in installation process: you can easily imagine installing an add-in on some two hundred PCs. In short, it is unpleasant for all sides of the process (you, the admin, and the user) to get the admin involved. The best practice is installing with non-admin permissions. To create such a setup you should know if the non-admin user has access rights to this or that folder / registry branch. Say, a standard user does not have access rights to Program Files and HKEY_LOCAL_MACHINE. If you know this, you target your setup project to the Application Data folder and HKEY_CURRENT_USER. In addition, you drop from your package every prerequisite that requires admin rights for installation.

The “non-administrative installation” theme has received its continuation in ClickOnce - a deployment technology introduced in .NET Framework 2.0. The name suggests that you can install some software in several clicks (let’s not waste time on trifles). When asked if COM add-ins can be installed with ClickOnce, Microsoft says no. Nevertheless, some clever guys in Add-in Express have found their own ClickOnce solution.

What are the tools?

You can create managed COM add-in using the following tools:

Every tool differs in the functionality it provides as well as in the shim it uses.

Shims are unmanaged DLLs used to make Office load managed code. When you register your unmanaged add-in, the shim info gets written to the registry (instead of targeting the add-in assembly) for Office to load the shim whenever the add-in is to be loaded. Thus, the shim becomes an essential part of the add-in development in .NET since it:

Shim comparison. Shared Add-ins are based on the universal shim installed with .NET Framework. It is called MSCOREE.DLL. VSTO add-ins are based on the VSTO Loader which is installed as part of VSTO run-time. The Add-in Express Loader is a custom shim that you install as part of your add-in installation. The Add-in Express Loader is configured via a manifest, it runs HKCU and HKLM targeted add-ins; it provides you with logging and allows installing the add-in when the previous version is being run. Also, note that Add-in Express supports the above-mentioned shims too. FYI, MSCOREE.DLL loads all Shared add-ins to the same AppDomain and in this way, one add-in can impede the work of other add-ins. In addition, you cannot sign it.

Office applications supported. All of the tools above support a number of Office applications. However, Shared Add-in and Add-in Express provide support for a broad set of Office applications (all Office versions), while VSTO confines itself to add-ins for Outlook 2003 only, and VSTO SE allows creating add-ins for 2003-2007 versions of Outlook, Excel, Word, PowerPoint, Visio, and for InfoPath 2007.

Office versions. Every tool allows developing for the currently installed Office version. Note, that every add-in developed for a given Office version will work for higher versions (with few exceptions). However, if you develop an add-in for Office 2003 in VSTO (VSTO SE), you will have to create another version of your add-in to access the features of Office 2007. Add-in Express provides Office 2000 interop assemblies. Thus, it makes possible to develop add-ins for Office 2000 no matter what Office version is installed on your development PC. What is more, your plug-ins developed with Add-in Express are version-independent, i.e. you write your code once and have the add-in work in all Office versions.

Setup. All of the tools above create an appropriate setup project automatically. However, with VSTO (VSTO SE) you will need to create custom actions for your add-in to get registered in .NET configs. With both VSTO and Shared Add-in you will have to configure your setup manually in order to allow non-admin installations. Note that Add-in Express simplifies and speeds up this part of add-in development: it allows choosing the installation type and provides ready-to-use custom actions.

ClickOnce. Shared Add-in doesn’t provide it. And as I pointed above, the VSTO ClickOnce wizard will not allow installing add-ins via ClickOnce. Add-in Express offers ClickOnce Solution that allows the end-user to install and update the add-in without the admin involved.

Development speed vs. flexibility. Shared Add-in and VSTO allow using all available Office interfaces and leave you face to face with them. The current Add-in Express version supports main interfaces only: COM add-in, Ribbon UI, and Custom Task Panes. To speed up the development, it provides components that solve typical problems of creating and using command bars (toolbars, menus, and context menus) and controls, Ribbon tabs, Office 2007 Menu, Quick Access Toolbar, custom task panes, keyboard shortcuts, as well as a number of Outlook–oriented components: Explorer and Inspector command bars, Outlook Bar shortcuts, and property pages for the Tools | Options and Folder Properties dialogs. In addition, Add-in Express provides unique plug-ins that allow embedding custom .NET forms into Outlook windows and custom .NET controls into Office toolbars.

Conclusion

Of course, I’m a bit biased. Nevertheless, if I just say that I love Add-in Express for .NET, it will be close to nothing. Add-in Express allows me to create the user interface of my add-in in minutes. I never spend too much time to create an Outlook Explorer command bar: I drop a component on the AddinModule and specify its properties (its name is the most essential one) and events. To create a task pane, I just add a UserControl to my project and bind it to the TaskPanes collection of the AddinModule using a combo box. And so on, and so forth. The development speed on this stage is beyond any expectations. I used to program add-ins in VB 6 and I say: I could not even imagine that such things are possible.
Well, of course, it is possible to live without Add-in Express: you can google out many useful things about command bars and their oddities when using them in some Office applications. You can also find many interesting things about this or that situation with this or that Office application. Just think of the time you will waste if using the “make-it-yourself” scenario. Say, it is easy to add a command bar in Outlook explorer window (list of mails). However, you will have to foresee the command bar’s behavior in multi-explorer and no-explorer scenarios (when Outlook is run via Automation). Then you’ll find that the command bar (and custom controls) can become disconnected spontaneously. Then you will have to debug it in all Outlook versions you plan to support. Isn’t it too much work for just to show a command bar?

Support. Support is an integral part of all Add-in Express product packages. I guess you’d better see customers’ opinions yourself. Try to search for the following through the currently available posts on our forums:

A couple of useful links:

Andrew Whitechapel. Microsoft .NET Development for Microsoft Office. Selected chapters
When ReleaseComObject is necessary in Outlook
IDTExtensibility2 Interface
IRibbonExtensibility
Microsoft: It is impossible to use ClickOnce for Office add-in deployment
Deployment of Managed COM Add-Ins in Office XP (contains additional info on shims)

Regards from Belarus,

Andrei Smolin
Add-in Express Team Leader

Related posts:

Customize Office toolbars, ribbons, task panes on RO Chrome
Make the Office 2007 Ribbon work easy

Customizing Office

Due to the Microsoft Office extensibility and Add-in Express components you can customize the Office UI including toolbars, menus, sub-menus, ribbons, task panes and property pages. In this example I describe three most important fields of Office customization - extending the Office UI, accessing Office objects and handling their events.

Creating custom toolbars for traditional Office 2000 – 2007 UI
With the command bar components described in part 2 of my RemObjects Chrome series you can add your own or customize any existing toolbars and menus in your host applications. For example, to add a new toolbar to the Outlook Explorer window, open and right click on the Add-in Designer, and then select the Add Explorer CommandBar item. This adds an adxOlExplorerCommandBar component. Next, select the added component and customize it through the Properties window using the CommandBarName, Position, Protection, UseForRibbon properties. The FolderNames and ItemTypes properties are Outlook-specific; you can use them to bind your toolbar to certain Outlook folders or specified content. For example, select Mail in the ItemTypes property to show your toolbar for mail folders only (see the picture below).

All command bar components have the Controls collection which is a container for controls of you toolbar. Using its designer you can add to your toolbar standard Office toolbar controls such as button, edit and combo boxes, pop-ups, etc. To add a button to the toolbar, select the Controls collection on the Properties window and open its designer. Then, click the Add button, select ADXCommandBarButton and customize it.

Then, create an event handler for the button click:


method AddinModule.adxCommandBarButton1_Click(sender: System.Object);
var
MailItem: outlook.MailItem;
begin
if OutlookApp.ActiveExplorer.Selection.Count > 0 then begin
MailItem := OutlookApp.ActiveExplorer.Selection.Item(1) as MailItem;
MessageBox.Show(MailItem.Subject);
end;
end;


Finally, register your project as an Office add-in. To do this, select the Register ADX Project item on the Build menu of your Visual Studio, run Outlook and click your button.

Third-party controls on Office toolbars
For Outlook, Excel, Word and PowerPoint you can use any third-party controls on Office toolbars. For example, let’s add a label that shows the subject of the selected mail.

First, you add to the add-in module a special component that supports third-party controls on Outlook toolbars. It is adxOutlookControlAdapter that you can find on the Toolbox; add it to the Add-in Designer. Next, add a label to the Add-in Designer and customize it through the Properties window.

Then, select your toolbar, open the Controls collection designer, click the Add button, select ADXCommandBarAdvancedControl and select the added label in the Control property.

To show the subject of the selected mail we need to handle the SelectionChange event. To do this, right click on the Add-in Designer, select Add Events, click Outlook Events on the opened window and click OK. This adds the Outlook events component to the Add-in Designer.

Using the Properties window, create an event handler for the ExplorerSelectionChange event:


method AddinModule.adxOutlookEvents_ExplorerSelectionChange(sender: System.Object; explorer: System.Object);
var
MailItem: outlook.MailItem;
begin
if OutlookApp.ActiveExplorer.Selection.Count > 0 then begin
MailItem := OutlookApp.ActiveExplorer.Selection.Item(1) as MailItem;
(Self.adxCommandBarAdvancedControl1.ActiveInstance as Label).Text := MailItem.Subject;
end;
end;


Finally, rebuild your project, run Outlook and select any mail. If you reproduce the steps above correctly, your label will show the subject of the selected mail item. Please note you needn’t register your project for the second time.

Customizing Office 2007 Ribbon UI
Add-in Express includes special components for the Ribbon UI customization. To create your own ribbon tab, right click on the Add-in Designer and select Add Ribbon Tab. This adds an adxRibbonTab component to the Add-in Designer. Next, name your tab via the Caption property and specify its ribbons via the Ribbons property (for example, select OutlookMailCompose).

Then, add a group and button to the tab through the Ribbon Tab designer of the Controls collection.

Next, handle the click of the button:


method AddinModule.adxRibbonButton1_OnClick(sender: System.Object;
control: AddinExpress.MSO.IRibbonControl; pressed: System.Boolean);
var
MailItem: outlook.MailItem;
begin
MailItem := OutlookApp.ActiveInspector.CurrentItem as MailItem;
if Assigned(MailItem) then
MailItem.Subject := 'Test';
end;


Finally, rebuild your project, run Outlook, create a new mail and click your button.

Adding application-level keyboard shortcuts
With Add-in Express you can easily create application-level keyboard shortcuts. To do this, click on the Add-in Designer, set its HandleShortcuts property to true, right click on the Add-in Designer and select Add Keyboard Shortcut. An adxKeyboardShortcut will be added to the Add-in Designer. Next, set the shortcut text to the ShortcutText property of the add-in component (Ctrl-Shift-R for this example).

Then, handle your shortcut action. In this example we reply to the currently selected mail and initialize its text:


method AddinModule.adxKeyboardShortcut1_Action(sender: System.Object);
var
MailItem: outlook.MailItem;
begin
if OutlookApp.ActiveExplorer.Selection.Count > 0 then begin
MailItem := OutlookApp.ActiveExplorer.Selection.Item(1) as MailItem;
MailItem := MailItem.Reply;
MailItem.Body := 'Test';
MailItem.Display(false);
end;
end;


Finally, rebuild your project, run Outlook and press Ctrl-Shift-R.

In this post I described only some of the features and capabilities that Add-in Express offers for customizing and enhancing your Office applications. To learn about other benefits provided by Add-in Express to .NET developers, visit Add-in Express home page

Related posts:

Make the Office 2007 Ribbon work easy
Create Office add-ins: ribbons, toolbars, task panes, menus
Create Microsoft Office extensions using RemObjects Chrome
Develop MS Office add-ins, smart tags, RTD servers on RO Chrome

The inside of your Office solution

By default, every Office solution (either COM add-in, RTD server, smart tag or UDF) based on Add-in Express includes two projects: the main project and a setup project. The first project is your extension itself, the second one you use to deploy the extension. Both projects include all necessary references and dependencies.

Security and deployment
Every solution based on Add-in Express templates is secure and deployable. Firstly, Add-in Express isolates your solution in its own AppDomain by a custom shim, the Add-in Express Loader, included in the setup project. The loader gives you the ability to update your add-in on the fly which makes deployment and redeployment very comfortable for your administrators. Secondly, the loader acts in accordance with the strict Office security model, so your Office add-ins run under the High Security setting.

RAD modules
Each of your solutions includes a special RAD module (AddinModule.pas in this example) which is the “heart” of your project. It is an analog of the Data Module in Borland Delphi that has its own visual designer. This module is a container for all Office-specific components and provides “access points” for handling Office objects. Thus, the RAD module is the place where your write your applied code.

In this example, the AddinModule class uses all necessary namespaces including AddinExpress.MSO. It is a descendant of ADXAddinModule and it implements several methods and properties (see the listing below; some insignificant code pieces are skipped).


namespace MyFirstOutlookAddin;

end.


The concept of designers
Open the Solution Explorer windows and click on AddinModule. You will see the Add-in Designer. As described above, it is a container for any components including Office-specific components delivered with Add-in Express. You can add any components from the Toolbox to the module, however Office-specific ones can be added only by the designer commands available by the right click of the mouse. You can add the following Office-specific components (see the picture below or right click on the Add-in Designer):

• Command bar – adds a new or customizes any existing toolbars of any Office applications.
• Outlook Explorer and Inspector command bar – used to create new or change any existing toolbars on the Outlook Explorer and Inspector windows.
• Built-in control connector – use it to intercept any ID-based control built in Office applications; for example, to handle the Save menu item in Word or the Send button in Outlook.
• Keyboard shortcut – provides the application-level keyboard shortcut; e.g. pressing Ctrl-Alt-S in Excel or Ctrl-F in PowerPoint.
• Outlook Bar shortcut manager – use it to create your own set of shortcuts on the Navigation Pane of Outlook.
• Ribbon tab – allows creating a new or customizing an existing tab on the ribbon context.
• Ribbon Quick Access Toolbar – enables you to create your own quick access toolbar.
• Ribbon Office menu – this component provides you with customization for the Office Menu in Office 2007 applications.
• Outlook forms manager – you add it to your project to customize Outlook views and forms using advanced Outlook regions.
• Event helpers – these components are used to handle all important events of all Office applications such as Outlook NewMail, Word DocumentBeforeSave, Excel WorkbookBeforeOpen, etc.
• The Host Configuration item is used to configure Office applications for a specified .NET Framework version.

Since AddinModule in this example is the central module of the project, it implements all COM-interfaces required by the COM Add-in technology and it has the base properties and events of COM add-ins (see the picture below). You can use the Properties window to name your add-in, to specify images for your toolbars and ribbon controls, to register your add-in for the current user or for all users, to collect and register your custom task panes and custom Outlook property pages, to define the namespace for your ribbon customization. Finally, using the SupportedApps property of your AddinModule you can enable / disable your extensions for certain Office applications. The events of your AddinModule include the common Office events for add-in initialization, finalization, error trapping, ribbon loading and task pane creation (see the picture below).

That’s all for now. In part three of the series, we will look more closely at the Office customization, namely creating your own toolbars for traditional Office 2000 – 2007 UI, customizing Office 2007 Ribbon UI and adding application-level keyboard shortcuts.

Related posts:

Create Microsoft Office extensions using RemObjects Chrome
Customize Office toolbars, ribbons, task panes on RO Chrome

In this three post series, I’ll be covering the most important concepts and approaches of creating custom Office extensions based on RO Chrome for Visual Studio and Add-in Express for Microsoft .net.

Today, I’ll dig a little bit into the history of Office application-level extensibility, highlight the key features of Add-in Express and show how to quickly get started with developing Outlook COM add-ins using Chrome and Add-in Express.

Office application-level extensibility

Microsoft Office has a long history of applications extensibility. Microsoft added the support for COM add-ins to Office 2000. In the first release of Microsoft Office 2002, the Smart Tags technology got supported. The second release of Office 2002 added Excel customization with Real-Time Data servers (RTDS) and Automation add-ins (user-defined functions). Finally, Office 2007 made the Ribbon UI customizable and extended the COM add-in technology for all Office applications. On the other hand, Microsoft released Visual Studio Tools for Office (VSTO) 2003 and 2005 that allow developers to extend Office with document- and application-level extensions. Unfortunately, VSTO supports VB.NET and C# only. Today on the development tools market there is only one tool that supports Offic