Architecture of Document-Level Customizations
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. |
Visual Studio Tools for Office includes projects for creating document-level customizations for Microsoft Office Word and Microsoft Office Excel. This topic describes the following aspects of Visual Studio Tools for Office customizations:
Understanding customizations
Components of customizations
How customizations work with the 2007 Microsoft Office system
How customizations work with Microsoft Office 2003
For general information about using Visual Studio Tools for Office customizations, see Office Solutions Development Overview, Getting Started Programming Document-Level Customizations for Word, and Getting Started Programming Document-Level Customizations for Excel.
Understanding Customizations
When you build a customization by using Visual Studio Tools for Office, you create a managed code assembly that is associated with a specific document. A document or workbook with a linked assembly is said to have managed code extensions. For more information, see Assemblies in Office Solutions Overview.
When a user opens the document, the assembly is loaded by the Microsoft Office application. After the assembly is loaded, the customization can respond to events while the document is open. The customization can also call into the object model to automate and extend the application while the document is open, 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 assembly in a different application domain. This means that one solution that behaves incorrectly cannot cause other solutions to fail. It also ensures that when the document is closed, all the code is shut down, and the assemblies are unloaded from memory. Document-level customizations are designed to work with a single document in a single application domain. They are not designed for cross-document communication. For more information about application domains, see Application Domains Overview.
Note
Document-level customizations that you create by using Visual Studio Tools for Office are designed to be used only when the application is started by an end user. If the application is started programmatically (for example, by using Automation), the customization might not work as expected.
Design-Time and Run-Time Experiences
To understand the architecture of Visual Studio Tools for Office solutions, it helps to understand the experiences of designing a solution and of running a solution.
Design Time
The design-time experience includes the following steps:
The developer creates a document-level project in Visual Studio. The project includes the document and the assembly that runs behind the document. The document might already exist (perhaps created by a designer), or a new document can be created along with the project.
The designer (either the developer who creates the project or someone else) creates the final look and feel of the document for the end user.
Run Time
The run time experience includes the following steps:
The end user opens a document or workbook that has managed code extensions.
The document or workbook loads the compiled assembly.
The assembly responds to events as the user works in the document or workbook.
Developer and End User Perspective Compared
Because the developer works primarily in Visual Studio, and the end user works in Word or Excel, there are two ways of understanding document-level customizations.
Developer's Perspective |
End User's Perspective |
|---|---|
Using Visual Studio, the developer writes code that is accessible to Word and Excel. Although it might seem that the developer is creating an executable file that runs Word or Excel, the process actually works the other way around. The document is associated with an assembly and contains a pointer to that assembly. When the document opens, Word or Excel locates the assembly and runs the code in response to all handled events. |
Those who use the solution simply open the document or workbook (or create a new document from a template) just as they would open any other Microsoft Office file. The assembly provides customizations in the document or workbook such as automatically populating it with current data, or showing a dialog box to request information. |
Supported Document Formats for Document-Level Customizations
When you create a customization project, you can choose the format of the document that you want to use in the project. For more information, see How to: Create Visual Studio Tools for Office Projects.
The following table lists the document formats you can use in document-level customizations for Excel.
Excel 2007 |
Excel 2003 |
|---|---|
Excel workbook (.xlsx) Excel macro-enabled workbook (.xlsm) Excel binary workbook (.xlsb) Excel 97-2003 workbook (.xls) Excel template (.xltx) Excel macro-enabled template (.xltm) Excel 97-2003 template (.xlt) |
Excel workbook (.xls) Excel template (.xlt) |
The following table lists the document formats you can use in document-level customizations for Word.
Word 2007 |
Word 2003 |
|---|---|
Word document (.docx) Word macro-enabled document (.docm) Word 97-2003 document (.doc) Word template (.dotx) Word macro-enabled template (.dotm) Word 97-2003 template (.dot) |
Word document (.doc) Word template (.dot) |
If you base a 2007 Microsoft Office customization on a document that was created in Microsoft Office 2003, Visual Studio Tools for Office does not change the file format of the document.
You should design managed code extensions only for documents in the supported formats. Otherwise, certain events might not be raised when the document opens in the application. For example, the Open event is not raised when you use managed code extensions with workbooks saved in the Excel XML spreadsheet format or in the Web page (.htm; .html) format.
Support for Word Documents That Have .xml File Name Extensions
The document-level project templates for Word 2003 and Word 2007 do not allow you to create projects based on the following file formats:
Word XML Document (*xml).
Word 2003 XML Document (*xml).
If you want your end users to use customizations in these file formats, build and deploy a customization that uses one of the supported file formats specified in the table above. After installing the customization, end users can save the document in the Word XML Document (*xml) format (for Word 2007) or the Word 2003 XML Document (*xml) format (for Word 2003), and the customization will continue to work as expected.
Components of Customizations
The main components of a customization are the document and the assembly. In addition to these components, there are several other parts that play an important role in how Microsoft Office applications discover and load customizations.
Deployment Manifest and Application Manifest
Customizations use deployment manifests and application manifests to identify and load the most current version of the customization assembly. The deployment manifest points to the current application manifest. The application manifest points to the customization assembly, and specifies the entry point class (or classes) to execute in the assembly. For more information, see Application and Deployment Manifests in Office Solutions.
Visual Studio Tools for Office Runtime
To run customizations that are created by using Visual Studio Tools for Office, end user computers must have the Visual Studio Tools for Office runtime installed. The Visual Studio Tools for Office runtime includes unmanaged components that load the customization assembly, and also a set of managed assemblies. These managed assemblies provide the object model that your customization code uses to automate and extend the host application.
For more information, see Visual Studio Tools for Office Runtime Overview.
How Customizations Work with the 2007 Microsoft Office System
When a user opens a document that is part of a 2007 Microsoft Office customization, the application uses the deployment manifest that is linked to the document to locate and load the most current version of the customization assembly. The location of the deployment manifest is stored in a custom document property named _AssemblyLocation. The string that identifies this location is inserted into the property when you build the solution.
The deployment manifest points to the application manifest, which then points to the most current assembly. For more information, see Application and Deployment Manifests in Office Solutions.
The following illustration shows the basic architecture of a customization for a 2007 Microsoft Office system document.
Customization architecture for the 2007 Microsoft Office system
.png "2007 Office customization architecture")
Loading Process for Customizations in the 2007 Microsoft Office System
The following steps occur when a user opens a document that is part of a 2007 Microsoft Office solution:
The Microsoft Office application checks the custom document properties to see whether there are managed code extensions associated with the document. For more information, see Custom Document Properties Overview.
If there are managed code extensions, 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.
If the document is opened from a location other than the local computer, the Visual Studio Tools for Office runtime verifies that the location of the document is in the Trusted Locations list in the Trust Center Settings for that particular Office application. If the document location is not in a trusted location, the customization is not trusted, and the load process stops here.
The Visual Studio Tools for Office runtime installs the solution if it has not been installed yet, downloads the most recent application and deployment manifests, and performs a series of security checks. For more information, see Security in Office Solutions (2007 System).
If the customization 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 customization assembly.
The Visual Studio Tools for Office runtime loads the customization assembly into the application domain.
The Visual Studio Tools for Office runtime calls the Startup event handler in your customization assembly. For more information, see Visual Studio Tools for Office Project Events.
How Customizations Work with Microsoft Office 2003
When a user opens a document that is part of a Microsoft Office 2003 customization, the application uses the application manifest that is embedded in the document to locate and load the most current version of the customization assembly. The embedded application manifest can point directly to the assembly, or it can point to a deployment manifest that is used to locate assembly updates. For more information, see Application and Deployment Manifests in Office Solutions.
The embedded application manifest is contained in an invisible embedded control called the Runtime Storage Control. For more information, see Runtime Storage Control Overview.
The following illustration shows the basic architecture of a customization for a Microsoft Office 2003 document.
Customization architecture for Microsoft Office 2003
.png "Office 2003 customization architecture")
Loading Process for Customizations in Microsoft Office 2003
The following steps occur when a user opens a document that is part of a 2003 Microsoft Office solution:
The Microsoft Office application checks the custom document properties to see whether there are managed code extensions associated with the document. For more information, see Custom Document Properties Overview.
If there are managed code extensions, the application loads AddinLoader.dll. This is an unmanaged DLL that is the loader component 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 an application domain, sets policy for the application domain not to trust the My Computer Zone, and checks the code access security policy store to find a policy for the customization assembly.
The .NET Framework validates the evidence presented by the assembly against the policy. If it fails, an error is raised. If it passes, the process continues.
If the customization 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 assembly into the application domain.
The Visual Studio Tools for Office runtime calls the Startup event handler in your customization assembly. For more information, see Visual Studio Tools for Office Project Events.
See Also
Concepts
Architecture of Application-Level Add-Ins
Visual Studio Tools for Office Runtime Overview
Creating Office Solutions in Visual Studio
Custom Document Properties Overview
Data Model in Document-Level Customizations
Runtime Storage Control Overview