文档级自定义项的体系结构Architecture of document-level customizations

Visual Studio 2013Visual Studio 2013 包括用于为 Microsoft Office Word 和 Microsoft Office Excel 创建文档级自定义项的项目。includes projects for creating document-level customizations for Microsoft Office Word and Microsoft Office Excel. 本主题介绍文档级自定义项的以下方面:This topic describes the following aspects of document-level customizations:

了解自定义Understand customizations

使用 Visual Studio 中的 Office 开发人员工具生成文档级自定义项时,会创建一个与特定文档关联的托管代码程序集。When you use the Office developer tools in Visual Studio to build a document-level customization, 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. 有关详细信息, 请参阅设计和创建 Office 解决方案For more information, see Design and create Office solutions.

当用户打开文档时,Microsoft Office 应用程序会加载程序集。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. 自定义项也可以调入对象模型,以便在文档处于打开状态时自动化和扩展应用程序,并且自定义项可以使用 .NET Framework.NET Framework中的任何类。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.NET Framework.

程序集通过应用程序的主互操作程序集与应用程序的 COM 组件进行通信。The assembly communicates with the application's COM components through the primary interop assembly of the application. 有关详细信息, 请参阅office 主互操作程序集office (解决方案)开发概述 VSTOFor more information, see Office primary interop assemblies and Office solutions development overview (VSTO).

如果用户同时打开多个文档级自定义项,则会在不同的应用程序域中加载每个程序集。If a user opens multiple document-level customizations at the same time, each assembly is loaded in a different application domain. 这意味着,一个行为不正确的解决方案不会导致其他解决方案失败。This means that one solution that behaves incorrectly cannot cause other solutions to fail. 文档级自定义项设计为与单个应用程序域中的单个文档协同工作。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.

Note

对于使用 Visual Studio 中的 Office 开发人员工具创建的文档级自定义项,仅当应用程序由最终用户启动时才会使用它。Document-level customizations that you create by using the Office developer tools in Visual Studio 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 document-level customizations, 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:

  1. 开发人员在 Visual StudioVisual Studio中创建文档级项目。The developer creates a document-level project in Visual StudioVisual Studio. 该项目包括文档和在该文档后端运行的程序集。The project includes the document and the assembly that runs behind the document. 文档可能已存在 (由设计器创建), 或可以与项目一起创建新文档。The document might already exist (created by a designer), or a new document can be created along with the project.

  2. 设计人员(无论是创建项目的开发人员还是其他人员)为最终用户创建文档的外观。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.

运行时Runtime

运行时体验包括下列步骤:The run-time experience includes the following steps:

  1. 最终用户打开具有托管代码扩展的文档或工作簿。The end user opens a document or workbook that has managed code extensions.

  2. 文档或工作簿加载已编译的程序集。The document or workbook loads the compiled assembly.

  3. 当用户在文档或工作簿中工作时,程序集对事件做出响应。The assembly responds to events as the user works in the document or workbook.

比较开发人员和最终用户的角度Developer and end-user perspective compared

因为开发人员主要在 Visual StudioVisual Studio中工作,而最终用户在 Word 或 Excel 中工作,所以可通过两种方式来了解文档级自定义项。Because the developer works primarily in Visual StudioVisual 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
开发人员使用 Visual StudioVisual Studio编写 Word 和 Excel 可以访问的代码。Using Visual StudioVisual Studio, the developer writes code that is accessible to Word and Excel.

尽管看上去可能像是开发人员正在创建一个运行 Word 或 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. 打开文档时,Word 或 Excel 会定位该程序集并针对所有已处理的事件运行代码。When the document opens, Word or Excel locates the assembly and runs the code in response to all handled events.
使用该解决方案的人员只需像打开任何其他 Microsoft Office 文件一样打开文档或工作簿(或根据模板创建新文档)即可。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. 有关详细信息,请参阅如何:在 Visual Studio中创建 Office 项目。For more information, see How to: Create Office projects in Visual Studio.

下表列出了可在 Excel 和 Word 的文档级自定义项中使用的文档格式。The following table lists the document formats you can use in document-level customizations for Excel and Word.

ExcelExcel Word
Excel 工作簿 ( .xlsx)Excel workbook (.xlsx)

启用宏的 Excel 工作簿 ( . xlsm)Excel macro-enabled workbook (.xlsm)

Excel 二进制工作簿 ( . .xlsb)Excel binary workbook (.xlsb)

Excel 97-2003 工作簿 ( .xls)Excel 97-2003 workbook (.xls)

Excel 模板 ( . xltx)Excel template (.xltx)

Excel 启用宏的模板 ( . xltm)Excel macro-enabled template (.xltm)

Excel 97-2003 模板 ( .xlt)Excel 97-2003 template (.xlt)
Word 文档 ( .docx)Word document (.docx)

启用宏的 Word 文档 ( . docm)Word macro-enabled document (.docm)

Word 97-2003 文档 ( .doc)Word 97-2003 document (.doc)

Word 模板 ( . dotx)Word template (.dotx)

Word 启用宏的模板 (normal.dotm)Word macro-enabled template (.dotm)

Word 97-2003 模板 ( .dot)Word 97-2003 template (.dot)

只应为格式受支持的文档设计托管代码扩展。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. 例如, 如果将Open托管代码扩展与保存为 Excel XML 电子表格格式或网页 ( .htm;) 的工作簿一起使用, 则不会引发事件。 .html)形式.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.

支持具有 .xml 文件扩展名的 Word 文档Support for Word documents that have .xml file name extensions

文档级项目模板不允许基于下列文件格式创建项目:The document-level project templates do not allow you to create projects based on the following file formats:

  • Word XML 文档 ( *xml)。Word XML Document (*xml).

  • Word 2003 XML 文档 ( *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. 安装自定义项后, 最终用户可以将文档保存为 word xml 文档 ( *xml) 格式或 word 2003 XML 文档 ( *xml) 格式, 并且自定义项将继续按预期方式工作。After installing the customization, end users can save the document in the Word XML Document (*xml) format or the Word 2003 XML Document (*xml) format, and the customization will continue to work as expected.

自定义组件Components of customizations

自定义项的主要组成部分是文档和程序集。The main components of a customization are the document and the assembly. 除了这些组成部分外,还有一些其他部件在 Microsoft Office 应用程序发现并加载自定义项的过程中扮演着重要角色。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. 有关详细信息, 请参阅Office 解决方案中的应用程序和部署清单For more information, see Application and deployment manifests in Office solutions.

Visual Studio Tools for Office RuntimeVisual Studio Tools for Office Runtime

若要运行通过使用 Visual Studio 中的 Office 开发人员工具创建的文档级自定义项, 最终用户计算机必须Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime安装。To run document-level customizations that are created by using the Office developer tools in Visual Studio, end-user computers must have the Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime installed. Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime 包括用于加载自定义项程序集的非托管组件,同时还包括一组托管程序集。The Visual Studio Tools for Office RuntimeVisual 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.

有关详细信息, 请参阅Visual Studio tools For Office runtime 概述For more information, see Visual Studio tools for Office runtime overview.

自定义项如何与 Microsoft Office 的应用程序一起工作How customizations work with Microsoft Office applications

当用户打开属于 Microsoft Office 自定义项的文档时,应用程序将使用链接到文档的部署清单来查找并加载自定义项程序集的最新版本。When a user opens a document that is part of a 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. 部署清单的位置存储在名为AssemblyLocation的自定义文档属性中。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. 有关详细信息, 请参阅Office 解决方案中的应用程序和部署清单For more information, see Application and deployment manifests in Office solutions.

下图展示了文档级自定义项的基本体系结构。The following illustration shows the basic architecture of a document-level customization.

2007 Office 自定义体系结构2007 Office customization architecture

Note

在面向 .NET Framework 4.NET Framework 4的 Office 解决方案中,解决方案通过使用嵌入解决方案程序集中的主互操作程序集 (PIA) 类型信息调入主机应用程序的对象模型,而不直接调入 PIA。In Office solutions that target the .NET Framework 4.NET Framework 4, solutions call into the object model of the host application by using primary interop assembly (PIA) type information that is embedded in the solution assembly, instead of calling into the PIA directly. 有关详细信息, 请参阅设计和创建 Office 解决方案For more information, see Design and create Office solutions.

正在加载进程Loading process

当用户打开属于 Microsoft Office 解决方案的文档时,将执行以下步骤。The following steps occur when a user opens a document that is part of a Microsoft Office solution.

  1. Microsoft Office 应用程序检查自定义文档属性,以确定是否有与文档关联的托管代码扩展。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.

  2. 如果存在托管代码扩展, 则应用程序将加载vstoee.dll, 后者将加载vstoloader.dllIf there are managed code extensions, the application loads VSTOEE.dll, which loads VSTOLoader.dll. 这些是非托管 Dll, 是 Visual Studio 2010 Tools for Office runtime 的加载程序组件。These are unmanaged DLLs that are the loader components for the Visual Studio 2010 Tools for Office runtime. 有关详细信息, 请参阅Visual Studio Tools for Office 运行时概述For more information, see Visual Studio Tools for Office runtime overview.

  3. Vstoloader.dll加载.NET Framework.NET Framework并启动的Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime托管部分。VSTOLoader.dll loads the .NET Framework.NET Framework and starts the managed portion of the Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime.

  4. 如果从本地计算机以外的位置打开文档, Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime 将验证文档的位置是否位于该特定 Office 应用程序的“信任中心设置” 中的“受信任位置” 列表中。If the document is opened from a location other than the local computer, the Visual Studio Tools for Office RuntimeVisual 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.

  5. Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime 将安装解决方案(如果尚未安装),下载最新的应用程序和部署清单,并执行一系列安全检查。The Visual Studio Tools for Office RuntimeVisual 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. 有关详细信息, 请参阅保护 Office 解决方案For more information, see Secure Office solutions.

  6. 如果自定义项受信任,可以运行,则 Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime 将使用部署清单和应用程序清单来检查程序集更新。If the customization is trusted to run, the Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime uses the deployment manifest and application manifest to check for assembly updates. 如果集有新版本的程序集可用,则运行时会将新版本的程序集下载到客户端计算机上的 ClickOnceClickOnce 缓存中。If a new version of the assembly is available, the runtime downloads the new version of the assembly to the ClickOnceClickOnce cache on the client computer. 有关详细信息, 请参阅部署 Office 解决方案For more information, see Deploy an Office solution.

  7. Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime 将创建一个要在其中加载自定义项程序集的新应用程序域。The Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime creates a new application domain in which to load the customization assembly.

  8. Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime 将自定义项程序集加载到应用程序域中。The Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime loads the customization assembly into the application domain.

  9. Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime 将在自定义项程序集中调用 Startup 事件处理程序。The Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime calls the Startup event handler in your customization assembly. 有关详细信息, 请参阅Office 项目中的事件For more information, see Events in Office projects.

请参阅See also