Visual Studio Tools for Office Runtime Overview

To run solutions that are created by using Visual Studio Tools for Office, end user computers must have the Visual Studio Tools for Office runtime. The runtime includes managed assemblies that provide the communication layer between your solution and the Microsoft Office application, and unmanaged components that the application uses to load your solution. 

For information about installing the runtime on end user computers, see How to: Install the Visual Studio Tools for Office Runtime.

This topic provides the following information:

  • Understanding the different runtime versions

  • Understanding the runtime assemblies

  • Understanding the runtime loader components

Understanding the Different Runtime Versions

Visual Studio Tools for Office solutions for different versions of Microsoft Office require different versions of the runtime. The runtime version is determined by the project template that was used to create the solution, not by the version of Office that is running the solution.

The following table shows which versions of the runtime and Microsoft Office are required to run solutions on the end user computer.

Project template version

Required Visual Studio Tools for Office runtime version on the end user computer

Microsoft Office versions that can run the solution on the end user computer

Projects for the 2007 Microsoft Office system

Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime)

2007 Microsoft Office system

Projects for Microsoft Office 2003

Visual Studio 2005 Tools for Office Second Edition runtime

2007 Microsoft Office system

Microsoft Office 2003

Both versions of the runtime are installed automatically on the development computer when you install Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0). 

For information about creating solutions that can run with both versions of Microsoft Office, see Creating Solutions for Multiple Versions of Microsoft Office.

There are some differences between the assemblies that are included in each version of the runtime. For more information, see Assembly Differences.

Note

The Visual Studio 2005 Tools for Office Second Edition runtime was initially released with Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (VSTO 2005 SE). This version of the runtime is also used by solutions for Microsoft Office 2003 that are created by using Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0).

Locating Reference Documentation for Both Runtimes

When you click a link or an index entry in Help to get reference information for a namespace, type, or member, you might get two almost identical results. The two topics document the same members in the two versions of the runtime. Select the topic that is identified by the appropriate version indicator:

  • 2007 System. This refers to the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime).

  • 2003 System. This refers to the Visual Studio 2005 Tools for Office Second Edition runtime.

Understanding the Runtime Assemblies

The assemblies that are included in the Visual Studio Tools for Office runtime provide the following categories of classes:

  • Classes that your solution uses to automate and extend the host application.

  • Infrastructure classes that enable your solution to communicate with the host application.

Note

When you create a project, Visual Studio Tools for Office automatically adds references to the assemblies that are used for the project type. Some of the assemblies are used only in document-level projects, and others are used only in application-level projects.

Assemblies in the Visual Studio Tools for Office 3.0 Runtime

The following table lists the assemblies that are included in the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime). This version of the runtime is used by solutions created for the 2007 Microsoft Office system.

For documentation about the namespaces and classes in these assemblies, see 2007 System Managed Reference.

Assembly name

Description

Microsoft.Office.Tools.Common.v9.0.dll

Provides the following classes:

  • The AddIn base class for application-level add-ins.

  • Classes for creating actions panes and smart tags in document-level customizations.

  • Classes for creating custom task panes in application-level add-ins.

  • Classes for creating Ribbon customizations.

  • The ExcelLocale1033Attribute and ExcelLocale1033Proxy classes, which are used by Excel solutions to control the locale ID (LCID) that is used for all culture-sensitive calls to the Excel object model. For more information, see Formatting Data in Excel with Various Regional Settings.

Microsoft.Office.Tools.Excel.v9.0.dll

Provides host items and host controls for Excel document-level customizations. For more information, see Host Items and Host Controls Overview.

Microsoft.Office.Tools.Outlook.v9.0.dll

Provides classes that you can use to create custom form regions in Outlook add-ins.

Microsoft.Office.Tools.Word.v9.0.dll

Provides host items and host controls for Word document-level customizations. For more information, see Host Items and Host Controls Overview.

Microsoft.Office.Tools.v9.0.dll

Provides the following classes:

  • The RemoteBindableComponent class, which provides the data binding capabilities for host controls in document-level customizations.

  • Other classes that are part of the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime) infrastructure, and are not intended to be used directly from your code.

Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll

Provides the following classes:

  • The CachedAttribute attribute and ICachedType classes, which you can use to cache data objects in a document-level customization.

  • Exceptions that can be thrown by the Visual Studio Tools for Office runtime.

  • Other classes that are part of the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime) infrastructure, and are not intended to be used directly from your code.

Microsoft.VisualStudio.Tools.Applications.ServerDocument.v9.0.dll

Provides the following classes:

  • The ServerDocument class, which you can use to programmatically attach customization assemblies to documents and to access the cached data in documents.

  • Several classes that represent the hierarchy of cached data in a document-level customization.

Microsoft.VisualStudio.Tools.Office.Runtime.v9.0.dll

Provides the following classes:

Microsoft.VisualStudio.Tools.Office.AppInfoDocument.v9.0.dll

Microsoft.VisualStudio.Tools.Office.Contract.v9.0.dll

Provide classes that are part of the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime) infrastructure. These classes are not intended to be used directly from your code.

Assemblies in the Visual Studio 2005 Tools for Office Second Edition Runtime

The following table lists the assemblies that are included in the Visual Studio 2005 Tools for Office Second Edition runtime. This version of the runtime is used by solutions created for Microsoft Office 2003.

For documentation about the namespaces and classes in these assemblies, see 2003 System Managed Reference.

Assembly name

Description

Microsoft.Office.Tools.Common.dll

Provides the following classes:

  • The AddIn base class for application-level add-ins.

  • Classes for creating actions panes and smart tags in document-level customizations.

Microsoft.Office.Tools.Excel.dll

Provides host items and host controls for Excel document-level customizations. For more information, see Host Items and Host Controls Overview.

Microsoft.Office.Tools.Word.dll

Provides host items and host controls for Word document-level customizations. For more information, see Host Items and Host Controls Overview.

Microsoft.VisualStudio.Tools.Applications.Runtime.dll

Provides the following classes:

  • The ServerDocument class, which you can use to programmatically attach customizations to documents and to access the cached data in documents.

  • The CachedAttribute attribute and ICachedType classes, which you can use to cache data objects in a document-level customization.

  • Exceptions that can be thrown by the Visual Studio Tools for Office runtime.

  • Other classes that are part of the Visual Studio 2005 Tools for Office Second Edition runtime infrastructure, and are not intended to be used directly from your code.

Assembly Differences

Several assemblies that are included in the Visual Studio 2005 Tools for Office Second Edition runtime have different names in the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime). In addition, one assembly that is part of the Visual Studio 2005 Tools for Office Second Edition runtime has been split into several new assemblies in the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime).

The following table lists the differences.

Assembly name in the Visual Studio 2005 Tools for Office Second Edition runtime

Assembly name in the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime)

Microsoft.Office.Tools.Common.dll

Microsoft.Office.Tools.Common.v9.0.dll

Microsoft.Office.Tools.Excel.dll

Microsoft.Office.Tools.Excel.v9.0.dll

Microsoft.Office.Tools.Word.dll

Microsoft.Office.Tools.Word.v9.0.dll

Microsoft.VisualStudio.Tools.Applications.Runtime.dll

Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll

Some classes have also been moved to the following new assemblies:

  • Microsoft.Office.Tools.v9.0.dll

  • Microsoft.VisualStudio.Tools.Applications.ServerDocument.v9.0.dll

Understanding the Runtime Loader Components

The Visual Studio Tools for Office runtime includes several unmanaged DLLs that Microsoft Office applications use to load Visual Studio Tools for Office solutions. Although you should never have to work with these DLLs directly, knowing the purposes of these DLLs can help you better understand the architecture of Visual Studio Tools for Office solutions.

For information about how these components are used during the load process, see Architecture of Document-Level Customizations and Architecture of Application-Level Add-Ins.

Runtime Loader

When a user opens a document-level customization or starts an add-in, the Microsoft Office application calls into the runtime loader. This component is named VSTOEE.dll.

The runtime loader ensures that the correct version of the Visual Studio Tools for Office runtime is loaded for the version of Microsoft Office that is loading the add-in. Although multiple versions of the Visual Studio Tools for Office runtime can be installed on the same computer, only one instance of VSTOEE.dll is installed at a time. This is the VSTOEE.dll that was included with the latest version of the runtime installed on the computer.

Solution Loader

The solution loader performs most of the work required to load the solution assembly. The solution loader has different file names depending on the version of the Visual Studio Tools for Office runtime. The solution loader in the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime) is named VSTOLoader.dll. In the Visual Studio 2005 Tools for Office Second Edition runtime, it is named AddinLoader.dll.

The solution loader does several things:

  • It creates a new application domain for each Visual Studio Tools for Office solution assembly.

  • It performs a set of security checks to verify that the add-in assembly has permission to run.

The solution loader also does several things that are specific to add-ins:

  • It implements the IDTExtensibility2 interface. IDTExtensibility2 is a COM interface that all add-ins for Microsoft Office applications must implement. This interface defines methods that the application calls to communicate with the add-in.

  • It implements the IManagedAddin interface. This interface is used by Office applications, starting in the 2007 release, to help load Visual Studio Tools for Office add-ins. For more information, see IManagedAddin Interface.

See Also

Tasks

How to: Install the Visual Studio Tools for Office Runtime

How to: Create Visual Studio Tools for Office Projects

Concepts

Architecture of Document-Level Customizations

Architecture of Application-Level Add-Ins

Upgrading and Migrating Office Solutions

Other Resources

Architecture of Visual Studio Tools for Office Solutions