Using the COM Add-in Shim to Trust Outlook 2002 Add-ins Built with Visual Studio .NET

Click here to download sample - odc_outlookcomshim.exe. This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

 

Randy Byrne
Micro Eye, Inc.

October 2002

Applies to:
    Microsoft® Outlook® 2002
    Microsoft Visual Studio® .NET

Summary: How to use the COM add-in shim solution template to trust an Outlook add-in using the Trusted Code page of the Administrative Security Form. A trusted add-in is not subject to the object model guard restrictions of the Outlook E-mail Security Update. (9 printed pages)

Download Odc_outlookcomshim.exe.

It's assumed that the reader:

  • Knows what a COM add-in is, and how to build, deploy, and install one. For more information about COM add-ins, take a look at What is a COM Add-in?.
  • Is familiar with the Outlook 2002 object model and the object model guard limitations imposed by the Outlook E-mail Security Update.
  • Is developing Outlook 2002 add-ins to be used in a Microsoft Exchange Server environment.
  • Has at least a beginning knowledge of .NET and COM interop.

Contents

Introduction
Outlook 2002 Code Security
Trusted Code Using the Administrative Form
The HelloCOMAddinVB Solution Adapted for Outlook
Conclusion
About the Author

Introduction

The COM add-in shim is a C++ project that allows developers of Microsoft® Office add-ins to trust their managed code add-ins. See Using the COM Add-in Shim Solution to Deploy Managed COM Add-ins in Office XP for more information. This article will demonstrate how to use the COM add-in shim project with a Microsoft Outlook® add-in developed using Microsoft Visual Basic® .NET. When you use the COM add-in shim with a managed code add-in, you can add the add-in to the Trusted Sources page of the Administrative Form in a Microsoft Exchange public folder. Add-ins that have been added to the Trusted Sources page are not subject to the object model guard restrictions of the Outlook E-mail Security Update.

Outlook 2002 Code Security

Outlook 2002 uses a different model than other Microsoft Office XP applications for code security. Be aware that the following remarks pertain only to Outlook 2002. Outlook 2000 uses a security model that resembles other Office 2000 applications like Microsoft Word and Microsoft Excel.

In Outlook 2002, all COM add-ins are trusted by default. Unlike Word and Excel, there is no check box or registry setting in Outlook that causes all add-ins to become untrusted by default when the application's macro security setting is set to Medium or High. In Outlook, the Macro Security Settings dialog box controls only the execution of Outlook Visual Basic for Applications (VBA) code. Macro security settings (Low, Medium, or High) do not influence the security settings for Outlook COM add-ins. Moreover, Outlook loads a COM add-in whether or not it has been digitally signed. Digital signatures do not influence the loading of COM add-ins in Outlook 2002. Instead, Outlook programmatic security is provided by the Outlook E-mail Security Update. For details about the Outlook E-mail Security Update including a list of properties and methods that cause the security warnings to appear, see the OL2002: Developer Information About E-Mail Security Features.

The object model guard in the Outlook E-mail Security Update displays the warning shown in Figure 1 when automation code attempts to access Recipient or AddressEntry objects. Outlook displays a different warning if your code attempts a programmatic send.

Aa140152.odc_outlookcomshim01(en-us,office.10).gif

Figure 1. Outlook address book security warning

Trusted Code Using the Administrative Form

If your managed code add-in uses blocked properties or methods of the Outlook object model, you should consider use of the Trusted Code feature of the Administrative Form to suppress Outlook warnings. When you add a COM add-in to the Trusted Code page of the Default Security Settings form in an Exchange public folder, the add-ins code is trusted and calls to restricted Outlook object model properties and methods do not display the warning dialog boxes. The Trusted Code mechanism operates as follows:

  1. The user must be connected to an Exchange server. The trust mechanism operates when the user is online or offline.
  2. A registry key named CheckAdminSettings with an appropriate DWORD value must be created under the HKEY_CURRENT_USER\Software\Policies\Microsoft\Security key for the trusted code settings to take effect.
  3. All trusted objects, properties, and methods must derive from the Application object passed in the OnConnection procedure of your add-in. If you instantiate a separate Outlook Application object and call blocked properties or methods on objects derived from the separate Application object, those methods and properties will be subject to the security warning.
  4. Only Outlook object model properties and methods can be unrestricted through the Administrative Form. You cannot provide unrestricted access to blocked Collaboration Data Objects (CDO) properties and methods.

You can install the Outlook E-mail Security Administrator Package (Admpack.exe) from one of the following locations:

  • The Microsoft Office Resource Kit Web site.
  • The Microsoft Office XP Enterprise CD located in the \Ork\Files\Pfiles\Orktools\Ork10\Tools\Admpack folder.

Why should you be concerned with the Outlook security warnings? Can't you advise your users just to click through the warning prompts? In short, you should be very concerned that you don't expose your organization to the cost and disruption of e-mail viruses. You should never educate users to click through the warning alerts, since you then open a security vulnerability to malicious worms and viruses that seek to exploit the Outlook object model.

For add-ins developed with Microsoft Visual Basic 6.0, trusting the add-in is a relatively straightforward matter for an Exchange administrator. The administrator uses the Trusted Code page to add your DLL to the list of trusted COM add-ins. However, if the administrator attempts to add your managed code add-in named MyAddin.dll to the list of trusted COM add-ins on the Administrative Form, the following problems could occur:

If the Administrator adds an add-in named MyAddin.dll on the Trusted Code page, MyAddin.dll will not be trusted. This trust fails because mscoree.dll provides the run-time implementation of MyAddin.dll.

  • If the Administrator adds mscoree.dll**on the Trusted Code page, all Outlook COM add-ins developed using Microsoft Visual Studio® .NET are trusted, including MyAddin.dll. This result is undesirable because you expose a security vulnerability to a managed code add-in that might be malicious.
  • See OL2002: COM Add-Ins Are Not Trusted If They Are Created with Visual Studio .NET for additional information.

To workaround these problems, you should build a COM add-in shim named MyAddinShim.dll for MyAddin.dll. The shim acts as a proxy for MyAddin.dll. If the Administrator trusts MyAddinShim.dll, then only the code in MyAddin.dll will be trusted from the perspective of the Administrative Form.

The HelloCOMAddinVB Solution Adapted for Outlook

To show you how to build a COM add-in shim for an Outlook add-in built using Visual Studio .NET, I've adapted the HelloCOMAddinVB solution that accompanies Using the COM Add-in Shim Solution to Deploy Managed COM Add-ins in Office XP. This adapted solution is available for download as odc_outlookcomshim.exe. You should familiarize yourself with the original COM add-in shim solution before you proceed.

Note   If you have already installed odc_comshim.exe that accompanies the original COM add-in shim solution, you should uninstall the COMAddinShim program using the Add/Remove Programs applet in Control Panel.

To Download the Sample HelloCOMAddinVB Solution

  1. Install the Office XP Primary Interop Assemblies (PIA) before you install the HelloCOMAddinVB solution. Download the Office XP PIAs.
  2. Download odc_outlookcomshim.exe from the link at the beginning of this article.
  3. Extract odc_outlookcomshim.exe to your My Documents folder. Use the folder names stored in the self-extracting file when you extract files in odc_outlookcomshim.exe. You should now have a folder named COMAddinShimTutorial under the MyDocuments folder.

The ComAddinShimTutorial folder contains the sample managed COM add-in Microsoft Visual Basic .NET project and the COM add-in shim project. The name of the COM add-in assembly is HelloCOMAddinVB. This project will be used to demonstrate how to create a COM add-in shim for Outlook.

  • To view this project, open HelloCOMAddinVB.sln located in C:\My Documents\COMAddinShimTutorial\HelloCOMAddinVB\.
  • The HelloCOMAddinVB folder also contains a subfolder with the name HelloCOMAddinVBSetup that contains the managed HelloCOMAddinVB setup project.

To Install the Sample HelloCOMAddinVB Solution

Note   Before installing the managed HelloCOMAddinVB COM add-in DLL, close Microsoft Outlook.

To install the COM add-in, do the following:

  1. To open the HelloCOMAddinVB project in Visual Studio .NET, open the HelloCOMAddinVB.sln file located at C:\My Documents\COMAddinShimTutorial\HelloCOMAddinVB\.
  2. You should find three projects in the Solution Explorer of the Visual Studio .NET IDE: COMAddinShim, HelloCOMAddinVB, and HelloCOMAddinVBSetup.
  3. First, rebuild the managed COM add-in by right-clicking on the HelloCOMAddinVB project and then clicking Rebuild.
  4. Next build the managed COM add-in setup project by right-clicking on the HelloCOMAddinVBSetup project and then clicking Build.
  5. You can now install the COM add-in by right-clicking on the HelloCOMAddinVBSetup project and then clicking Install. This will launch the HelloCOMAddinVB setup wizard.
  6. Click Next.
  7. In the Select Installation Folder dialog box, accept the default or supply a different installation folder.
  8. Click Next.
  9. Click Next to install HelloCOMAddinVB.

To Test HelloCOMAddinVB

  1. Restart Outlook.

  2. You will see an Outlook security warning similar to the one shown in Figure 1. The code in the OnConnection event has accessed the name property of the CurrentUser object and causes the security warning to appear.

  3. If you select the Allow Access For check box and then click Yes, the name of the current user will be displayed in a message box as shown in Figure 2.

    Aa140152.odc_outlookcomshim02(en-us,office.10).gif

    Figure 2. Current user name displayed by HelloCOMAddinVB

The code in HelloCOMAddinVB modifies the code in the original HelloCOMAddinVB project to use a property that is blocked by the Outlook E-mail Security Update, CurrentUser.Name. In the OnConnection event of the add-in, a message box displays the name of the current user as follows:

Public Sub OnConnection(ByVal application As Object, _
        ByVal connectMode As Extensibility.ext_ConnectMode, _
        ByVal addInInst As Object, ByRef custom As System.Array) _
        Implements Extensibility.IDTExtensibility2.OnConnection
    Dim m_Outlook As Application
    Dim m_Namespace As [NameSpace]
    Dim strUserName As String
    applicationObject = application
    addInInstance = addInInst
    m_Outlook = applicationObject
    m_Namespace = m_Outlook.GetNamespace("MAPI")
    strUserName = m_Namespace.CurrentUser.Name
    MsgBox("Current User: " & strUserName, MsgBoxStyle.Information)
    'Instantiate event-aware objects
    m_olApp = applicationObject
    m_olExplorers = m_olApp.Explorers
    m_olInspectors = m_olApp.Inspectors
    m_olExplorer = m_olApp.ActiveExplorer
End Sub

It bears repeating that trusted objects in your code must derive from the applicationObject passed into the OnConnection event. If you create a new Outlook Application object in the OnConnection procedure or elsewhere in your code, the objects derived from that separate Outlook Application object are not trusted. All trusted objects, properties, and methods must derive from the applicationObject passed into the add-in's OnConnection event.

For additional information concerning coding practices for an Outlook add-in built with Visual Basic .NET, see Building Outlook 2002 Add-ins with Visual Basic .NET.

To Trust HelloCOMAddinVB

In order to trust HelloCOMAddinVB, you must have first installed the Outlook Administrative Form in the Outlook Security Settings folder and added the correct CheckAdminSettings key to the registry. You will need to restart Outlook twice before any Administrative Form settings take effect. See the readme.doc that is installed in the folder where you extracted admpack.exe for detailed instructions concerning installation and use of the Default Security Form. The following instructions are for an Exchange administrator or a user that has installed the Administrative Form on their machine and has at least Editor Permissions on the Outlook Security Settings public folder.

  1. Copy HelloCOMAddinVBShim.dll (located in C:\My Documents\COMAddinShimTutorial\HelloCOMAddinVB\bin)**to a location where the administrator creating the security setting has access to it.

    **Note   **Remember that you will trust HelloCOMAddinVBShim.dll rather than HelloCOMAddinVB.dll.

  2. On the Trusted Code tab, click the Add button and select HelloCOMAddinVBShim.dll.

  3. Click the Close button on the form and then click the Yes button when Outlook prompts you to save changes.

Aa140152.odc_outlookcomshim03(en-us,office.10).gif

Figure 3. Use the Administrative Form to trust the COM Add-in Shim

Once HelloCOMAddinVBShim.dll has been trusted, you should not see the warning dialog box shown in Figure 1. If you continue to see the warning dialog box, make sure that the CheckAdminSettings registry key has been set correctly on the test machine. The shim DLL acts as a proxy for the managed code add-in, HelloCOMAddinVB.dll, and allows the Outlook trust mechanism to extend only to a specific managed code add-in rather than to all add-ins that use the common language runtime engine, mscoree.dll.

**Note   **Add-ins created with Visual Basic 6.0 must be re-trusted when they are recompiled. The Administrative Form calculates and stores a hash on the compiled DLL and uses this hash for trust verification when Outlook boots. An interesting side effect of the shim solution is that once you have created and trusted your COM add-in shim, you do not have to re-trust your managed code add-in if you recompile. The hash on the shim DLL controls trust verification.

To Trust Your Add-in

The sample HelloCOMAddinVB solution is designed to provide a pre-built example for trusting a managed code Outlook add-in using a COM Add-in shim and the Administrative Form. If you want to adapt the COM add-in shim to your own managed code add-in, an extensive series of steps are required. These steps are described in detail in Using the COM Add-in Shim Solution to Deploy Managed COM Add-ins in Office XP.

Be aware that the steps described in the above MSDN article apply to a Word add-in. There are some steps that are not required for an Outlook add-in that will be trusted on the Trusted Code page of the Administrative Form. Other steps must be modified for an Outlook add-in. You can omit or modify the following steps when you add a COMAddInShim project to your managed COM add-in project:

  • Adding a digital signature to the shim DLL and the managed COM add-in DLL is not required.
  • Be sure to correctly change the GUIDs and ProgIDs in the sample COMAddinShim project to the correct GUIDs and ProgIDs for your managed code add-in. Failure to change these values will cause the proxy shim to operate incorrectly.
  • The unmanaged shim's ProgID must be registered under HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER depending upon whether you want the shim to be visible in the Outlook COM Add-Ins dialog box. Add-ins registered under HKEY_LOCAL_MACHINE are not visible in the Outlook COM Add-Ins dialog box. Assuming the ProgID of your shim is MyCOMAddInShim.Connect, you must add the following code at the end of the ConnectProxy.rgs file.
HKCU
{
    NoRemove Software
    {
        NoRemove Microsoft
        {
            NoRemove Office
            {
                NoRemove Outlook
                {
                    NoRemove Addins
                    {
                        ForceRemove MyComAddInVBShim.Connect 
                                {
                                     val 'Description' = s 'MyDesc'
                                     val 'FriendlyName' = s 'MyName'
                                     val 'LoadBehavior' = d 3
                                }
                    }
                }
            }
        }
    }
}

Conclusion

When you incorporate the COM add-in shim solution template to your managed COM add-in project, you will be able to add your Outlook 2002 managed code add-in to the Trusted Code page of the Administrative Form in an Exchange public folder. Adding your add-in shim to the list of trusted sources will prevent the display of the warning dialog boxes associated with the Outlook E-mail Security Update if you call blocked properties or methods in the Outlook object model.

About the Author

Randy Byrne is the president of Micro Eye, Inc., a Microsoft Certified Partner located in the San Francisco Bay Area. He is an Outlook Most Valued Professional (MVP) and the author of Building Applications with Microsoft Outlook 2000 and Building Applications with Microsoft Outlook Version 2002 published by Microsoft Press.