Architecture of Application-Level Add-Ins
Applies to |
|---|
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type
Microsoft Office version
For more information, see Features Available by Application and Project Type. |
The add-ins that you create by using Visual Studio Tools for Office have architectural features that emphasize stability and security, and enable them to work closely with Microsoft Office. This topic describes the following aspects of Visual Studio Tools for Office add-ins:
Understanding add-ins
Components of add-ins
How add-ins work with the 2007 Microsoft Office system
How add-ins work with Microsoft Office 2003
Shutdown behavior of Outlook 2003 add-ins
For general information about using Visual Studio Tools for Office add-ins, see Office Solutions Development Overview and Getting Started Programming Application-Level Add-Ins.
Understanding Add-Ins
When you build an add-in by using Visual Studio Tools for Office, you create a managed code assembly that is loaded by a Microsoft Office application. After the assembly is loaded, the add-in can respond to events that are raised in the application (for example, when a user clicks a menu item). The add-in can also call into the object model to automate and extend the application, and it can use any of the classes in the .NET Framework.
The assembly communicates with the application's COM components through the primary interop assembly of the application. For more information, see Office Primary Interop Assemblies and Office Solutions Development Overview.
Visual Studio Tools for Office loads each add-in in a different application domain. This means that one add-in that behaves incorrectly cannot cause other add-ins to fail. It also ensures that when the application is closed, all the code is shut down, and the assemblies are unloaded from memory. For more information about application domains, see Application Domains Overview.
Note
Add-ins that you create by using Visual Studio Tools for Office are designed to be used only when the host Microsoft Office application is started by an end user. If the application is started programmatically (for example, by using Automation), the add-in might not work as expected.
Components of Add-Ins
Although the add-in assembly is the main component, there are several other components that play an important role in how Microsoft Office applications discover and load add-ins.
Registry Entries
Microsoft Office applications discover add-ins by looking for a set of registry entries. Most of the registry entries are the same for the 2003 and 2007 releases of Microsoft Office, but one key is different:
Applications in the 2007 Microsoft Office system look for the Manifest entry under the key HKEY_CURRENT_USER\Software\Microsoft\Office\application name\Addins\add-in ID (or, for Visio, HKEY_CURRENT_USER\Software\Microsoft\Visio\Addins\add-in ID). The Manifest entry specifies the full path of the deployment manifest.
Microsoft Office 2003 applications look for the ManifestName and ManifestLocation entries under the key HKEY_CURRENT_USER\Software\Microsoft\Office\application name\Addins\add-in ID (or, for Visio, HKEY_CURRENT_USER\Software\Microsoft\Visio\Addins\add-in ID). These entries specify the location and name of the application manifest.
When you build your solution, Visual Studio Tools for Office creates all of the required registry entries on the development computer so that you can debug and run your add-in. For more information, see Office Solution Build Process Overview.
For a complete list of the registry entries used by add-ins, see Registry Entries for Application-Level Add-Ins.
Note
You can deploy a Visual Studio Tools for Office add-in for Microsoft Office 2003 so that it is available to all users of a computer by creating the registry keys under HKEY_LOCAL_MACHINE instead of HKEY_CURRENT_USER. However, you cannot deploy a Visual Studio Tools for Office add-in for the 2007 Microsoft Office system to all users of a computer by registering the add-in under HKEY_LOCAL_MACHINE. Applications in the 2007 Microsoft Office system only recognize Visual Studio Tools for Office add-ins that are registered under HKEY_CURRENT_USER.
Deployment Manifest and Application Manifest
Add-ins use deployment manifests and application manifests to identify and load the most current version of the add-in assembly. The deployment manifest points to the current application manifest. The application manifest points to the add-in assembly, and specifies the entry point class to execute in the assembly. For more information, see Application and Deployment Manifests in Office Solutions.
Visual Studio Tools for Office Runtime
To run add-ins that are created by using Visual Studio Tools for Office, end user computers must have the Visual Studio Tools for Office runtime installed. The runtime includes unmanaged components and a set of managed assemblies. The unmanaged components load the add-in assembly. The managed assemblies provide the object model that your add-in code uses to automate and extend the host application.
For more information, see Visual Studio Tools for Office Runtime Overview.
How Add-ins Work with the 2007 Microsoft Office System
When a user starts an application in the 2007 Microsoft Office system, the application uses the deployment manifest and the application manifest to locate and load the most current version of the add-in assembly. The following illustration shows the basic architecture of these add-ins.
Add-in architecture for the 2007 Microsoft Office system
.png "2007 Office add-in architecture")
Loading Process
The following steps occur when a user starts an application:
The application checks the registry for entries that identify add-ins that were created by using Visual Studio Tools for Office.
If the application finds these registry entries, the application loads VSTOEE.dll, which loads VSTOLoader.dll. These are unmanaged DLLs that are the loader components for the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime). For more information, see Visual Studio Tools for Office Runtime Overview.
VSTOLoader.dll loads the .NET Framework and starts the managed portion of the Visual Studio Tools for Office runtime.
The Visual Studio Tools for Office runtime checks for manifest updates, and downloads the most recent application and deployment manifests.
The Visual Studio Tools for Office runtime performs a series of security checks. For more information, see Security in Office Solutions (2007 System).
If the add-in is trusted to run, the Visual Studio Tools for Office runtime uses the deployment manifest and application manifest to check for assembly updates. If a new version of the assembly is available, the runtime downloads the new version of the assembly to the ClickOnce cache on the client computer. For more information, see Deploying Office Solutions (2007 System).
The Visual Studio Tools for Office runtime creates a new application domain in which to load the add-in assembly.
The Visual Studio Tools for Office runtime loads the add-in assembly into the application domain.
The Visual Studio Tools for Office runtime calls the RequestComAddInAutomationService method in your add-in, if you have overridden it.
You can optionally override this method to expose an object in your add-in to other Microsoft Office solutions. For more information, see Calling Code in Application-Level Add-ins from Other Solutions.
The Visual Studio Tools for Office runtime calls the RequestService method in your add-in, if you have overridden it.
You can optionally override this method to extend a feature in the 2007 Microsoft Office system by returning an object that implements an extensibility interface. For more information, see Customizing UI Features By Using Extensibility Interfaces.
The Visual Studio Tools for Office runtime calls the ThisAddIn_Startup method in your add-in. This method is the default event handler for the Startup event. For more information, see Visual Studio Tools for Office Project Events.
Note
The Visual Studio Tools for Office runtime makes separate calls to the RequestService method for each extensibility interface that is supported by the host application. Although the first call to the RequestService method usually happens before the call to the ThisAddIn_Startup method, your add-in should not make any assumptions about when the RequestService method will be called, or how many times it will be called.
How Add-ins Work with Microsoft Office 2003
When a user starts a Microsoft Office application, the application uses information in the application manifest (and, optionally, the deployment manifest) to load the add-in assembly. The following illustration shows the basic architecture of an add-in for a Microsoft Office 2003 application.
Add-in architecture for Microsoft Office 2003
.png "Office 2003 add-in architecture")
Loading Process
The following steps occur when a user starts an application:
The application checks the registry for entries that identify add-ins that were created by using Visual Studio Tools for Office.
If the application finds these registry entries, the application loads VSTOEE.dll, which loads AddinLoader.dll. These are unmanaged DLLs that are the loader components for the Visual Studio 2005 Tools for Office Second Edition runtime. For more information, see Visual Studio Tools for Office Runtime Overview.
AddinLoader.dll loads the .NET Framework and starts the managed portion of the Visual Studio Tools for Office runtime.
The Visual Studio Tools for Office runtime creates a new application domain, sets policy on the application domain not to trust the My Computer Zone, and checks the code access security policy store to find a policy for the add-in assembly.
The .NET Framework validates the evidence presented by the assembly against the policy of the application domain. If it fails, an error is raised. If it passes, the process continues.
If the add-in uses a deployment manifest, the Visual Studio Tools for Office runtime uses it to check for assembly updates. If any updates are necessary, they are performed now.
The Visual Studio Tools for Office runtime loads the add-in assembly into the new application domain.
The Visual Studio Tools for Office runtime calls the RequestComAddInAutomationService method in your add-in, if you have overridden it.
You can optionally override this method to expose an object in your add-in to other Microsoft Office solutions. For more information, see Calling Code in Application-Level Add-ins from Other Solutions.
The Visual Studio Tools for Office runtime calls the ThisAddIn_Startup method in your add-in. This method is the default event handler for the Startup event. For more information, see Visual Studio Tools for Office Project Events.
Shutdown Behavior of Outlook 2003 Add-Ins
If you are migrating an existing Outlook 2003 COM add-in (that is, an add-in that directly implements the IDTExtensibility2 interface) to Visual Studio Tools for Office, remove any code that is designed to work around potential shutdown problems. Otherwise, this code might conflict with the shutdown process for Outlook 2003 add-ins created by using Visual Studio Tools for Office, or your add-in might be unloaded prematurely.
Note
The behavior described in this section does not apply to Outlook 2007 add-ins. Outlook 2007 always calls the OnDisconnection method in an add-in, even if the add-in still has references to Outlook objects.
Background of the Shutdown Issue
As long as a COM add-in has a reference to one or more Outlook objects, Outlook 2003 does not call the OnDisconnection method in the add-in. If the add-in has object references that are cleaned up only in the OnDisconnection method, Outlook 2003 never calls the OnDisconnection method. As a result, the add-in is never unloaded, and Outlook 2003 never shuts down.
How Visual Studio Tools for Office Resolves the Shutdown Issue
Outlook 2003 add-ins created by using Visual Studio Tools for Office are unloaded in a way that avoids this potential problem. The Visual Studio Tools for Office runtime raises the Shutdown event of the add-in and unloads the application domain of the add-in if the add-in does not have references to any Explorer or Inspector objects when one of the following occurs:
When the application domain is unloaded, all outstanding references to other Outlook objects are cleaned up, and Outlook 2003 can then shut down the add-in and exit.
See Also
Concepts
Architecture of Document-Level Customizations
Visual Studio Tools for Office Runtime Overview
Programming Application-Level Add-Ins