Using AddinSpy and AS Diagnostic Tools for Microsoft Office Add-ins

  • Article

Summary: AddInSpy is a diagnostic tool that discovers all registered Microsoft Office add-ins on a computer, and then reports as much information as it cannot about those add-ins. The tool works with all versions of all Microsoft Office applications that support COM add-ins, and all types of COM add-ins. (15 printed pages)

Andrew Whitechapel, Microsoft Corporation

September 2008

Applies to: 2007 Microsoft Office System, Microsoft Office 2003, Microsoft Office XP, Microsoft Office 2000, Microsoft Visual Studio 2008, Microsoft Visual Studio Tools for the Microsoft Office system (3.0), Microsoft Visual Studio 2005 Tools Second Edition for the 2007 Microsoft Office System

Contents

  • Overview

  • Requirements for Using AddInSpy and AS

  • AddInSpy Options

  • AS Options

  • Viewing Scan Results

  • Understanding Report Output

  • Development Notes

  • Test Notes

  • Known Issues and Limitations

  • Conclusion

  • Additional Resources

Overview

AddInSpy and AS are two variants of the same tool: a diagnostic tool that is intended for use while developing add-ins for 2007 Microsoft Office system, Microsoft Office 2003, Microsoft Office XP, or Microsoft Office 2000. You can also use it to troubleshoot issues with deployed add-ins.

Important noteImportant

This tool is unsupported.

Download AddInSpy

The tool discovers and reports more information than is available through the Microsoft Office user interface. AddInSpy is a standalone Windows Presentation Foundation application, while AS is a scriptable console application. Both AddInSpy and AS are simple front-end applications that share the AddInScanEngine.dll, which contains all the main scanning functionality. The scan engine scans the registry for Microsoft Office add-ins, and reports the following details:

  • Whether the host application is running, and whether the add-in is loaded.

  • The type of each add-in, such as add-ins built with Visual Studio Tools for Microsoft Office, managed add-ins not built with Visual Studio Tools for Microsoft Office, or native add-ins.

  • FriendlyName, ProgID, CLSID and LoadBehavior of the add-in.

  • Manifest path, assembly path, and assembly strongname.

  • Registry hive (HKCU or HKLM) where the add-in is registered.

  • Common Language Runtime (CLR)version the add-in was built against.

  • Visual Studio Tools for Microsoft Office runtime version used by the add-in.

  • Installed date, and publish version.

  • Which extensibility interfaces that the add-in implements such as custom Microsoft Office Fluent Ribbons or custom task panes (including wrappers created by using Visual Studio Tools for Microsoft Office).

  • Whether the add-in exposes itself for automation through the COMAddIns collection of the Microsoft Office host application.

  • Whether the add-in is in the disabled items list for the current user, for each selected Microsoft Office host application.

  • Whether the add-in is registered as the provider for any custom form regions.

  • Context information: machine name, user and domain name, operating system details, Visual Studio Tools for Microsoft Office environment variables.

The data is reported in a grid, which offers all the usual options for sorting, column sizing, column reordering, and cell editing, as shown in Figure 1.

Figure 1. AddInSpy main window

AddInSpy main window

If you double-click any row in the grid, AddInSpy displays a dialog with the data for just that add-in. This format makes it slightly easier to read the data than in the main grid, as shown in Figure 2.

Figure 2. Data for a single add-in

Data for a single add-in

From the command bar in AddInSpy or using command-line arguments with AS, you can configure information to include in the scan, including:

  • Which Microsoft Office applications to include in the scan.

  • Which registry hives to scan, that is, HKCU and/or HKLM.

  • Whether or not to scan for assembly information for add-ins registered to remote locations.

  • Whether or not to scan for extensibility interfaces in managed add-ins and/or in native add-ins .

  • Whether or not to check whether each add-in is in the disabled items list for this user.

  • Whether or not to scan cross-check each add-in against registered custom form regions (Microsoft Outlook add-ins).

  • Whether or not the scan report should include context information (machine, user name, etc) and/or add-in data.

Requirements for Using AddInSpy and AS

  • Microsoft .NET CLR 2.0 and Microsoft .NET Framework 3.5.

  • AddInSpy and AS do not require administrative privileges to run.

  • On computers running Windows Vista, AddInSpy and AS work with user account control either on or off.

  • AddInSpy and AS are both 32-bit applications. They run on either 32-bit or 64-bit editions of Windows. The first release of the tool targets 32-bit Office, and will not work with 64-bit Office.

AddInSpy Options

To perform a scan, you can select the options you want to include in the scan, and then click Refresh to execute the scan. You can then change any options and either turn on the Auto-refresh behavior, or click Refresh again when you want to execute a new scan. When you want to output a report, you can select which type of information to include in the report, and then click Report.

  • The options for configuring the scan are located on the command bar at the top of the AddInSpy window. This is shown in Figure 3.

    Figure 3. AddInSpy command bar

    AddInSpy command bar

  • The list of Microsoft Office host applications for which you can perform the scan is provided in the Hosts combo box.You can select any Microsoft Office host application that supports COM add-ins, that is: Microsoft Office Access, Microsoft Office Excel, Microsoft Office FrontPage, Microsoft Office InfoPath, Microsoft Office Outlook, Microsoft Office PowerPoint, Microsoft Office Project, Microsoft Office Publisher, Microsoft Office SharePoint Designer, Microsoft Office Visio or Microsoft Office Word. You can select any number or combination of these, as shown in Figure 4.

    Figure 4. AddInSpy Hosts combo box

    AddInSpy Hosts combo box

  • The Scans combo box provides a list of scan types, as shown in Figure 5. Specifically, whether AddInSpy should scan the HKCU and/or HKLM registry hives; add-ins registered to remote locations (UNC and HTTP); extensibility interfaces implemented in managed add-ins; extensibility interfaces implemented in native add-ins; the disabled items list for this user for each selected application; and Office Outlook custom form regions registered against each add-in. Note that scanning remote add-ins may be slow, especially if the network connection is slow. Also, if the network or remote location cannot be found, this is reported as an error in the Status description field.

    Figure 5. AddInSpy Scans combo box

    AddInSpy Scans combo box

  • Refresh performs a complete scan or re-scan, using the current settings.

  • If you select the Auto-refresh option, this forces an immediate re-scan when any of the other options are changed.

  • The Report combo box shown in Figure 6 provides a list of information to output to the report: that is, either computer and user context information or add-in information, or both.

    Figure 6. AddInSpy Report combo box

  • Clicking Report produces a report to a file on disk.

  • Clicking Help displays a simple help document in a Web browser window, as shown in Figure 7. Note that for this to work, the file AddInSpy.mht must be in the same folder as AddInSpy.exe.

    Figure 7. AddInSpy Help window

    AddInSpy Help window

  • The status bar at the bottom of the AddInSpy main window displays the context information, as shown in Figure 8. This information includes the machine name, the current user’s domain user-name, the operating system version and service pack number, and the status of the VSTO_SUPPRESSDISPLAYALERTS and VSTO_LOGALERTS environment variables. Note that the Refresh feature also refreshes the computer and user information, but environment variables are not refreshed during the process run.

    Figure 8. AddInSpy status bar

    AddInSpy status bar

AS Options

AS is the scriptable console version of the add-in scanner and offers the same options as AddInSpy. To perform a scan with AS, you specify command line arguments for the options you want to include in the scan, and a report is produced automatically.

AS takes arguments in any order, and is not case-sensitive. Spaces are required between option lists, but no spaces are allowed anywhere else in the command line. Each argument must be prefixed with either a dash “-“ or a forward slash “/”, and followed by an equals sign “=”, then a comma-separated list of values. In each case, you can supply either the full argument name or its abbreviation. For example, either “/h=” or “/hosts=”

Table 1. AS Options

Option

Abbreviation

Description

hosts

H

The comma-separated list following this option specifies the Microsoft Office application hosts to include in the scan. The following values are allowed in this list:

  • Office Access

  • Office Excel

  • Office InfoPath

  • Office Outlook

  • Office PowerPoint

  • Office Project

  • Office Publisher

  • Office SharePointDesigner (note no space)

  • Office Visio

  • Office Word

report

R

The comma-separated list following this option specifies the types of data to include in the report. The following values are allowed in this list:

  • context

  • addins

scans

S

The comma-separated list following this option specifies the types of scan to perform. The following values are allowed in this list:

  • HKCU

  • HKLM

  • Remote

  • ManagedInterfaces

  • NativeInterfaces

  • DisabledItems

  • FormRegions

output

O

The single argument following this option specifies the filename to use for the scan report. This may be a simple filename, in which case it is saved to the current directory or, it can be a fully-qualified path. If no output option is provided, the report defaults to a file name made up from the IP address of the computer and the current user’s user/domain name (for example, baad..f00d.beef.f00f.fefe%10_andrew@MYDOMAIN.xml). It is placed on the current user’s desktop.

Examples of valid command lines are given in the following table. Note that each command line is a single line.

Table 2. Valid Command Lines

Example Command Line

Description

as /h=Excel,Outlook,Word /s=HKCU,HKLM,ManagedInterfaces,NativeInterfaces,DisabledItems /r=Context,AddIns

Scan add-ins for OfficeExcel, Office Outlook and Office Word only. Scan both HKCU and HKLM registry hives. Scan both managed and native add-ins for extensibility interfaces. Cross-check each add-in to see if it is in the disabled items list for each specified host, for the current user. Do not scan for add-ins deployed to remote locations. Do not scan for Office Outlook custom form regions. In the report, include both context information and add-in data.

as /hosts=excel,outlook,word /scans=hkcu,hklm,managedinterfaces,nativeinterfaces /reports=addins

Scan add-ins for Office Excel, Office Outlook and Office Word only. Scan both HKCU and HKLM registry hives. Scan both managed and native add-ins for extensibility interfaces. Do not scan for add-ins deployed to remote locations. Do not scan for Office Outlook custom form regions. Do not scan for disabled items. In the report, include only add-in data, not context information.

as -H=all -S=HKCU,HKLM,DisabledItems -R=all

Scan add-ins for all Microsoft Office host applications. Scan both HKCU and HKLM registry hives. Cross-check each add-in to see if it is in the disabled items list for each specified host, for the current user. Do not scan for extensibility interfaces. Do not scan for add-ins deployed to remote locations. Do not scan for Office Outlook custom form regions. In the report, include both context information and add-in data.

as /h=all /s=all /r=all

Scan add-ins for all Microsoft Office host applications. Perform all possible scans. Include all types of data in the report.

as /h=all /s=all /r=all /o=C:\Temp\MyReport.xml

Scan add-ins for all Microsoft Office host applications. Perform all possible scans. Include all types of data in the report. Save the report to a file named MyReport.xml in the path C:\Temp.

Viewing Scan Results

In AddInSpy, the grid reports a check or alert icon in the OK? field to indicate the overall status of each add-in. If all information about the add-in is correct (registration, assembly paths, etc), then the overall status is checked. If there are inconsistencies in the add-in’s registration or loadability, or any error from the scanning operation for the add-in, this is reported with an alert icon. Any invalid or uncertain status is also reported in the Status description field. These values are represented as either OK or Alert in the report and in the AS output.

  • For example, the Office Word add-ins WebPage.Connect and WordEEFonts.Connect, and the Office Project add-in DBU.dsrDBU are no longer deployed, but have redundant Microsoft Office registry entries. The specific error in these cases is that the Microsoft Office registry keys for the add-in do not map to any COM CLSID registration.

  • As another example, during testing we built an add-in that was registered and run against multiple hosts (Office Excel 2003, Office Excel 2007 and Office Word 2003) and was designed to cause the host application to crash – so that the add-in would then be listed in the disabled items list for that host. Note that this particular scan relies on parsing a binary registry entry, and may not be completely reliable.

  • Note that multiple registrations for an add-in is not necessarily an error. If an add-in is registered multiple times (possibly against different Microsoft Office host applications), this is reported with a warning message in the Status description field.

  • When AddInSpy scans native add-ins for secondary extensibility interfaces, it does so by loading the add-in DLL independently of the host. However, some add-ins – including the Office Outlook add-ins AccessAddin.DC (Microsoft Access Outlook Add-in for Data Collection and Publishing), ColleagueImport.ColleagueImportAddin (Microsoft Office SharePoint Server Colleague Import Add-in), and UmOutlookAddin.FormRegionAddin (Microsoft Exchange Unified Messaging) – cannot be loaded independently of the host. This is reported in the Status description for these add-ins.

Understanding Report Output

  • In AddInSpy, in addition to displaying the scan results in the grid, you can optionally output a report to an XML file. When you click Report, AddInSpy displays a FileSave dialog, and allows you to specify the name and location of the report file. If you omit an extension, AddInSpy adds the “.xml” extension for you.

  • The AS console tool always outputs a report to an XML file. You can specify the name and location of this file using the /o command-line option.

  • The report format for AddInSpy and AS is the same. Figure 9 shows a cut-down example of a report, listing the context information and one add-in.

Figure 9. Extract from a sample report from AS or AddInSpy

Extract from a sample report

Development Notes

To better understand what the scanner is doing, and how it functions, it is instructive to note some of the internal implementation details.

  • At the time of writing there is no Windows Presentation Foundation datagrid control in the standard library, and we did not want to take a dependency on any external library. So instead, the application hosts the Windows Forms DataGridView in a custom UserControl in Windows Presentation Foundation. The code is structured to use a proxy layer between the grid control and the rest of the application, so that we can easily rip and replace the hosted grid when a grid control becomes available in the standard library for Windows Presentation Foundation.

  • The tool reflects over the add-in (in the case of managed add-ins), or calls QueryInterface on the add-in (if it is native) to find all the extensibility interfaces it supports. These interfaces are:

    • IRibbonExtensibility

    • ICustomTaskPaneConsumer

    • FormRegionStartup

    • IBlogExtensibility

    • IBlogPictureExtensibility

    • EncryptionProvider

    • SignatureProvider

    • IDocumentInspector

The tool loads the add-in DLL independently of any instance that might be running. This allows the tool to query for interfaces on all add-ins, not just the ones that happen to be loaded in running applications at the time. In the case of managed add-ins, this is done using ReflectionOnlyLoadFrom, which also ensures that no code runs. In the case of native add-ins, this is done by using Activator.CreateInstance., which does not ensure that no code runs - you should bear this in mind if you choose the option to scan for extensibility interfaces in native add-ins.

  • The tool can tell whether an add-in implements an interface directly, or uses any of the Visual Studio Tools for Microsoft Office wrappers. These wrappers are:

    • Microsoft.Office.Tools.Outlook.FormRegionControl

    • Microsoft.Office.Tools.Ribbon.OfficeRibbon

    • Microsoft.Office.Tools.CustomTaskPaneCollection

  • The code uses ComImport to define the COMAddIn and COMAddIns interfaces, which therefore eliminates the need for any dependency on Office DLLs or primary interop assemblies (PIAs). String type names are used for the Microsoft.Office.Tools.Ribbon.OfficeRibbon and Microsoft.Office.Tools.Outlook.FormRegionControl types, which eliminates the need for any dependencies on the Visual Studio Tools for Microsoft Office runtime.

Test Notes

This tool is unsupported, because only minimal testing was done. Tests were conducted on the 64-bit editions of Windows Vista, Microsoft Windows XP x86, with Microsoft Office 2000, 2002, 2003 or the 2007 Microsoft Office system.

Test cases include the following:

  • Add-ins for all Microsoft Office applications that support COM add-ins (Office Access, Office Excel, Office FrontPage, Office InfoPath, Office Outlook, Office PowerPoint, Office Project, Office Publisher, Office SharePoint Designer, Office Visio, Office Word)

  • Add-ins for all versions of Microsoft Office that support COM add-ins (from Office 2000 onwards).

  • Native (unmanaged) add-ins

  • Managed add-ins not created with Visual Studio Tools for Microsoft Office

  • Add-ins created with Microsoft Visual Studio 2005 Tools Second Edition

  • Add-ins created with Microsoft Visual Studio 2005 Tools for the Microsoft Office System, where the Microsoft Office registry entries do not map to corresponding COM registry entries.

  • Add-ins created with Microsoft Visual Studio 2008

  • Add-ins correctly registered, including locally installed, locally published, and published to remote locations (including network shares and HTTP locations)

  • Add-ins registered to HKCU and/or HKLM (including HKLM\Wow6432Node for 32-bit add-ins registered on a 64-bit platform)

  • Add-ins that implement one or more of the extensibility interfaces, with and without the Visual Studio Tools for Microsoft Office wrappers

  • Add-ins registered to invalid paths, or paths where the DLL is not found

  • Add-ins registered to network paths, when the network is disconnected or the remote share is unreachable

  • Invalid manifests, including badly-formed XML, and invalid or missing key elements.

  • Add-ins incorrectly registered in multiple registry hives (such as, the Visual Studio Tools for Microsoft Office Word and Excel Design Time Adaptors).

Exceptions are treated as follows:

  • Some expected exceptions are just accepted. An example of this is the COMException thrown when Marshal.GetActiveObject fails. This is how we determine that a host is not running, and is an expected exception.

  • Other expected exceptions are reported in the Status description field. For example if you have an add-in (with dependencies to the primary interop assemblies for the 2007 Microsoft Office system) registered on a computer with only Microsoft Office 2003 installed. In these cases, the raw exception message is reported.

  • In a few cases, an exception is reported only to a debug window (with Debug.WriteLine). For example if our assembly resolver cannot find all dependencies, it is not useful to report this because the tool does not actually need the dependencies for anything.

  • Other unexpected exceptions are reported in the Status description field.

Known Issues and Limitations

  • If you deploy the add-in to an HTTP URL, the tool does not attempt to determine its installation date, assembly strong name, CLR version, or interfaces. The main issue here is that we cannot load the locally-copied HTTP-deployed DLL for reflection, because there may be dependent assemblies which would also normally be in obfuscated locations in the ClickOnce cache, and we cannot resolve these (unless we recursively scan the entire cache) at this time.

  • With this release, for add-ins created with Visual Studio Tools for Microsoft Office, we use the deployment manifest to find the latest version of the assembly, but this is not necessarily the version that is getting loaded on the computer.

  • Microsoft Office sees a native add-in shim (such as the shims produced by the COM Shim Wizard) as regular native add-ins. Microsoft Office cannot distinguish between a native add-in and a native shim. The tool also cannot distinguish these at this time.

Conclusion

You can use the tool, AddInSpy, and the command-line version, AS, to determine a host of information about Microsoft Office add-ins of all types. Due to test limitations, this tool is unsupported but is available for your use. This tool is compatible with both the 64-bit editions of Windows Vista and 32-bit editions of Windows Vista, and Windows XP. It identifies invalid add-in registration, hard- and soft-disabled states, which extensibility interfaces each add-in supports, publish information, CLR version information, and more.

Additional Resources

For more information, see the following resources: