Visual Studio Tools for Office: Using C# with Excel, Word, Outlook, and InfoPath [Electronic resources] نسخه متنی

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.

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.

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:

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 files\Common Files\Microsoft Shared\VSTO\8.0 directory.

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_USER\Software\ Microsoft\Office\Outlook\Addins, we will find a registry key for the add-in we created in VSTO called OutlookAddin1 in our example, as shown in Chapter 23. These registry entries make Outlook think it is just loading a COM add-in.

If we search the registry under the HKEY_CLASSES_ROOT\CLSID 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.

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

<assembly xmlns="urn:schemas-microsoft-com:asm.v1" xmlns:asmv2="urn:schemas-microsoft-com
:asm.v2" manifestVersion="1.0">
<assemblyIdentity name="OutlookAddin1.manifest" version="1.0.0.0" />
<asmv2:entryPoint name="Startup" dependencyName="dependency0">
<asmv2:clrClassInvocation />
</asmv2:entryPoint>
<asmv2:dependency asmv2:name="dependency0">
<asmv2:dependentAssembly>
<assemblyIdentity name="OutlookAddin1" version="1.0.0.0"  culture="neutral" />
</asmv2:dependentAssembly>
<asmv2:installFrom codebase="OutlookAddin1.dll" />
</asmv2:dependency>
</assembly>

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 Projects\OutlookAddin1\OutlookAddin1\bin\debug\OutlookAddin1.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.

This causes a manifest to be generated that is slightly different from the manifest in 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.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.