The Office Primary Interop Assemblies (PIAs)

Creating an Outlook Add In in VSTO

To create an Outlook add-in in VSTO, choose Project from the New menu of the File menu. The Outlook add-in project appears in the list of templates under the Visual C#/Office node in the tree of project types, as shown in Figure 24-6. Type a name for your new Outlook add-in project and pick a location for the project. Then click the OK button.

Figure 24-6. Creating a new Outlook add-in project.

A project is created with references to the Outlook 2003 PIA, the core Office PIA, and other needed references, as shown in Figure 24-7. One project item is created in the project called ThisApplication.cs.

Figure 24-7. The Outlook add-in project in Solution Explorer.

If you double-click the ThisApplication.cs project item, you will see a simple code view, shown in Listing 24-2, that looks very similar to the ThisDocument.cs project item in the Word document or template VSTO project or the Sheet1.cs project item in the Excel workbook or template project. There is a simple Startup and Shutdown method where you can write code that executes on the startup and shutdown of the add-in. Startup is roughly the equivalent of OnConnection in IDTExtensibility2-based add-ins, and Shutdown is roughly the equivalent of OnDisconnection. Listing 24-2 also illustrates that the ThisApplication class derives from an aggregate of the Outlook Application object, enabling you to access properties and methods of the Outlook Application object by writing code such as this.Inspectors.Count.

Listing 24-2. ThisApplication.cs for an Outlook Add-In Project

using System;
using System.Windows.Forms;
using Microsoft.VisualStudio.Tools.Applications.Runtime;
using Office = Microsoft.Office.Core;
using Outlook = Microsoft.Office.Interop.Outlook;

namespace OutlookAddin1
{
 public partial class ThisApplication
 {
 private void ThisApplication_Startup(object sender, EventArgs e)
 {
 MessageBox.Show(String.Format(
 "There are {0} inspectors and {1} explorers open.",
 this.Inspectors.Count, this.Explorers.Count));
 }

 private void ThisApplication_Shutdown(object sender, EventArgs e)
 {
 MessageBox("Goodbye");
 }

 #region VSTO Designer generated code
 private void InternalStartup()
 {
 this.Startup += new EventHandler(ThisApplication_Startup);
 this.Shutdown += new EventHandler(ThisApplication_Shutdown);
 }
 #endregion
 }
}

When you run the project with the code shown in Listing 24-2, Outlook is launched and the add-in loads and displays a dialog box showing the count of the Inspectors and Explorers. Now go to Outlook's COM Add-In dialog by following these steps:

1.	Choose Options from the Tools menu to bring up the Options dialog.
2.	Click the Other tab of the Options dialog.
3.	Click the Advanced Options button to bring up the Advanced Options dialog.
4.	Click the COM Add-Ins button to bring up the COM Add-Ins dialog.

Figure 24-8 shows the COM Add-Ins dialog. The add-in you just created (OutlookAddin1) is displayed as if it were a COM add-in. If you look at the location of the add-in, it claims to be in the C:program filesCommon FilesMicrosoft SharedVSTO8.0 directory.

Figure 24-8. The COM Add-Ins dialog shows the VSTO Outlook add-in.

From the standpoint of Outlook, Outlook believes it is loading a COM add-in even though we know this is a VSTO Outlook add-in project. What is going on here? To answer that, let's do a little digging in the registry to understand how VSTO is hooking everything up. If we look under HKEY_CURRENT_USERSoftware MicrosoftOfficeOutlookAddins, we will find a registry key for the add-in we created in VSTO called OutlookAddin1 in our example, as shown in Figure 24-9. The registry entries look just like those for an IDTExtensibility2 add-in as described in Chapter 23. These registry entries make Outlook think it is just loading a COM add-in.

Figure 24-9. A VSTO Outlook Add-in registered under the Outlook Addins subkey.

If we search the registry under the HKEY_CLASSES_ROOTCLSID key for the ProgID OutlookAddin1, we will find a key associated with the OutlookAddin1 ProgID. Looking under the InProcServer32 key for that ProgID, we see the entries in Figure 24-10.

Figure 24-10. The InProcServer32 under the CLSID key associated with ProgID OutlookAddin1.

Under the InProcServer32 key are several important values. First, the (Default) value is the DLL that Outlook will start up to load the VSTO Outlook add-in we created. The DLL name is AddinLoader.dll. This is a VSTO-provided replacement for mscoree.dll that can load a managed add-in without the problems associated with mscoree.dll listed at the start of this chapter. This DLL also solves the Outlook shutdown problem, making it so that your add-in will always shut down cleanly and not leave Outlook running.

Second, we see a ManifestLocation key. Because the VSTO Outlook add-in project uses the VSTO runtime to load the add-in, a manifest is required to specify what to load. This manifest is identical to the manifest embedded in VSTO customized Word documents and Excel spreadsheets. The name of the manifest is stored in the ManifestName key. If we go to the ManifestLocation and open the file with the name ManifestName (OutlookAddin1.manifest), we will see the XML shown in Listing 24-3.

Listing 24-3. The OutlookAddin1.manifest File

[View full width]

:asm.v2" manifestVersion="1.0">
 
 
 
 
 
 
 
 
 
 

The manifest indicates that the actual managed add-in assembly that AddinLoader.dll will load is called OutlookAddin1.dll. The path provided in codebase will be relative to the location of the manifest (specified in ManifestLocation). So looking at the ManifestLocation key in Figure 24-10, we can see that the VSTO runtime will load OutlookAddin1.dll from the full path below:

C:Visual Studio ProjectsOutlookAddin1OutlookAddin1indebugOutlookAddin1.dll

Security

VSTO Outlook add-ins use the same security model that Word and Excel VSTO customizations use. That is, no Outlook add-in runs without .NET Framework security policy that trusts the Outlook add-in assembly and any dependent assemblies. When you create a new Outlook add-in project, Visual Studio automatically adds this policy to trust the bin directory for the project and any referenced assemblies that are copied locally to the project directory. When you deploy an Outlook add-in, however, you need to also create and install .NET policy that will trust the assemblies that are part of the Outlook add-in. Chapters 19, ".NET Code Security," and 20, "Deployment," cover this in more detail.

The VSTO security model is also the key to how the "Trust all installed templates and add-ins" problem is solved. When this check box in the Macro Security dialog is unchecked, Office requires the InProcServer32 registered for the add-in to be signed. Because VSTO's security model is that no add-in runs without .NET Framework security policy to trust it, VSTO can sign the AddinLoader.dll because it will only load code that has been trusted by .NET Framework security policy. This makes it so that your add-in will load even in environments where this check box is not checked.

Manifest Updating

VSTO Outlook add-ins use the same basic updating and publishing mechanism that Word and Excel VSTO customizations use to update the manifest in a document. You can publish a VSTO Outlook add-in that embeds in the manifest a URL to a deploy manifest. To publish an add-in, right-click the project node in Solution Explorer and choose Publish from the pop-up menu. The Publish Wizard shown in Figure 24-11 will appear. Here we choose to publish to a local directory called c:myaddins.

Figure 24-11. Publishing a VSTO Outlook add-in.

This causes a manifest to be generated that is slightly different from the manifest in Listing 24-3. The first difference is the manifest now points to a deploy manifest. Each time an Outlook add-in that has been published and has a deploy manifest location is loaded, the deploy manifest is checked to see whether a newer version of the manifest is available. If there is, a new version of the manifest is pulled down to the ManifestLocation specified in the registry, and it overwrites the old manifest. The second difference is that DLLs referred to in the application manifest are now located relative to the path to the deploy manifest instead of the application manifest. For more information on publishing and deploy manifests, see Chapter 20, "Deployment."

Installing

VSTO Outlook add-ins differ in one important way from Word and Excel VSTO customizations: They must be registered in the registry. This means that you will have to have an installer that installs your add-in onto a user's machine and puts the needed registry keys in the registry.

When you create a VSTO Outlook add-in project, a setup project for the add-in is automatically created for you. This setup project will generate an installer that puts the required registry keys in the registry and copies the manifest and add-in DLL to the desired location. It does not install the VSTO runtime redistributable (vstor.exe) or configure .NET security policy to trust the add-in. These steps must either be added manually to the setup project or performed as a separate step when rolling out VSTO to an enterprise. For more information, see Chapter 20.

Other VSTO Features

Although it would be nice, Outlook add-ins do not support VSTO's Smart Tags or ActionsPane features that are available to Word and Excel customizations. It also does not support the cached data feature of VSTO.