VSTA的简单集成.docx

概述Microsoft Visual Studio Tools for Applications 2012（VSTA）使你的用户可以使用Visual Basic 语言或 Visual C# 语言定制现有的应用程序。你可以在你的应用程序中使用Visual Studio集成开发环境（IDE），以使你的应用程序支持用户定制。最终用户开发者能通过使用 IDE 创建加载项的方法定制应用程序，以便他们能根据需要拓展应用程序的功能。 使用 Visual Studio Tools for Applications 2012 Visual Studio Tools for Applications 2012 提供了两种主要的模式：与 Visual Studio 2012 Professional、Premium 或 Ultimate 一起使用和独立使用。 在独立使用的模式下， VSTA 为你的应用提供加载、编译和运行用户自定义功能的途径。在与 Visual Studio 2012 Professional、Premium 或 Ultimate 一起使用时，VSTA只负责编辑和调试那些自定义功能。Visual Studio Tools for Applications 2012为你的应用程序集成设计时支持提供了一种崭新的、简单的API。宿主应用程序可以支持整合托管（Visual C# 或 Visual Basic .NET）和非托管（Visual C+）代码。VSTA 集成 API 能够让你像用Visual Studio一样简单的方法如“启动外部进程” “ 同步保存状态”拓展你的应用程序。Visual Studio Tools for Applications 2012 支持升级并编译和运行Visual Studio 2005 Tools for Applications 和Visual Studio 2008 Tools for Applications开发的项目。Visual Studio Tools for Applications 2012不需要最终用户自定义运行库。这让应用程序能灵活地选择最适应宿主应用程序的用户代码运行方法。Microsoft .NET Framework包含了加载项框架，这可以用于运行用Visual Studio 2008 Tools for Applications创建的加载项。最低系统要求： Windows 7 .NET Framework 4.5 2 GB 的内存 4 MB 的硬盘空闲空间运行时要求： Visual C+ Redistributable for Visual Studio 2012 Update 1编译和调试工具： Microsoft Visual Studio 2012 Professional、Premium 或 Ultimate开始为了让应用程序整合Visual Studio Tools for Applications 2012，你必须理解一些简单的概念。定义宿主应用程序： 一个能够通过用户代码扩展的应用程序。宿主应用程序是使用了VSTA技术并支持最终用户代码编译和运行的“主机”。 集成开发环境（IDE） ：一个应用程序（这里指Visual Studio 2012） 允许用户编辑、编译和调试代码。项目模板：一个源文件和 XML 文件的集合，用于在运行时创建自定义的最终用户代码。会话：一个可以和IDE关联的项目集合的实例。 它封装了所有的服务，这些服务包含了零个或更多项目和一个运行着的IDE实例之间能完成的事情。 VSTAX：一个开放的包装容器（OPC）文件，其中包含一个或多个项目的模板。VSTAX文件通常是由宿主应用程序供应商创建的、附带在应用程序中的，它用于在运行时创建一个用户自定义项目。VSTA 包含了集成托管和非托管代码的 API。本文档将演示如何在Visual C# 中使用API，不过你也可以在Visual C+ 或 Visual Basic .NET中使用它。 安装 Visual Studio Tools for Applications 2012 SDK在你运行该版本的 VSTA之前，必须安装 Microsoft .NET Framework 4.5 。除了VSTA之外你还需下载Microsoft ships a software development kit (SDK) for VSTA（用于VSTA的微软软件开发工具包）。在安装了VSTA SDK 之后，它的组件就会被放置到Program Files (x86)Microsoft SDKsVSTA11.0 文件夹中。本文档中的例子中使用了Visual Studio 2012，其实对于创建一个应用程序你只需要 .NET Framework SDK （可从微软免费下载）就足够了。从你的宿主应用程序程序启动IDE在安了VSTA SDK 后，你可以使用 Visual C# 在你的应用程序中添加一组引用，并编写三行代码，从而使你可以从你的应用程序启动Visual Studio 。 用应用程序启动IDE： 1. 在 Visual Studio 2012 中创建一个 WPF 应用程序，并命名为“MyVSTAHost”。2. 在 解决方案资源管理器 中打开MyVSTAHost 节点的 快捷菜单 并选择 添加引用 。3. 在 添加引用 对话框中选择 Microsoft.VisualStudio.Tools.Applications version ，然后单击 添加 按钮。4. 在默认窗体中添加一个按钮控件，然后为这个按钮控件添加一个事件。5. 向窗体添加以下语句：using VSTA = Microsoft.VisualStudio.Tools.Applications;6. 向刚才添加的事件中添加以下代码： private VSTA.Session _session; private void button1_Click(object sender, EventArgs e) if (_session = null) var sessionMgr = VSTA.SessionManager.Create(MyHostApp); _session = sessionMgr.CreateSession(); _session.Ide.Show(); 这段代码的作用如下：1. 如果尚未创建会话，将先创建一个会话，这是应用程序与IDE交互和管理项目的基础。2. 在会话 IDE 实例中显示 IDE 。这将隐式启动 IDE 进程，并打开一个应用程序与 IDE 交互的通道，然后让 IDE 显示主窗口。注意： 在正在运行的宿主应用程实例中，会话的名字在上下文中必须是唯一的。 也就是说 “if(_session = null)”条件阻止了用户因单击按钮造成具有相同名称的其它会话在同一时间被创建，这将会导致IDE对象的访问被锁死。 如果你使用了Session 和SessionManager对象 ，你必须在适当的时候调用IDisposable方法，以便保持这些对象的实例，否则这些实例将会被 .NET 的垃圾处理机制释放掉。创建项目模板为了创建VSTA项目，你必须选择一个项目模板。该模板提供了使最终用户添加自己的代码到解决方案所需的项目源文件的基本框架。在VSTA中，项目模板封装在vstax文件里。这些文件包含一个或多个模板，可以和你的宿主应用程序一起分发。这些项目模板的工作方式与部署在 Visual Studio 2012 中的项目模板不同，VSTA项目模板不要求安装 Visual Studio 。VSTA项目模板的部署可以被宿主应用程序完全控制。VSTA项目模板提供了内置的对通配符的支持 （例如“$projectname$”）， 生成的GUID（例如“$guid2$”），也提供了创建项目的过程中对 SNK 文件生成的支持。 你可以使用 TemplateGenerator.exe 创建VSTA项目模板，这是一个包含在VSTA SDK中的命令行工具，你可以在 %ProgramFiles(x86)%Microsoft SDKsVSTA11.0Tools 目录中找到它。这个工具可以创建一个供VSTA使用的VSTAX 文件。创建一个模板：1. 在Visual Studio 2012中创建一个C# 类库项目，并命名为“TemplateProject”。2. 把 Class1 重命名为“AddIn” ，并添加下面的方法：public static void Init() / 在这里添加启动代码3. 把 AddIn.cs 文件中所有的“TemplateProject” 替换成“$safeprojectname$”， 当项目被从模板创建时，通配符将会被替换成实际的项目名。a. 把AssemblyInfo.cs 文件中所有的“TemplateProject” 替换成“$safeprojectname$”， 当项目被从模板创建时，通配符将会被替换成实际的项目名。把Guid 属性 中的GUID替换成“$guid2$” ，通配符将会被替换成实际生成的GUID。b. 把 TemplateProject.csproj 文件中所有的“TemplateProjec” 替换成“$safeprojectname$”， 当项目被从模板创建时，通配符将会被替换成实际的项目名。把 ProjectGuid 节点的内容替换成“$guid1$” ，通配符将会被替换成实际生成的GUID。像后面那样，在PropertyGroup 节点中添加“”节点。这一步后的两个GUID分别代表了VSTA和 C# 项目类型。如果要创建Visual Basic的项目模板，可以把 C# 项目模板的 GUID （FAE04EC0-301F-11D3-BF4B-00C04F79EFBC）替换成 Visual Basic 项目模板的 GUID （F184B08F-C81C-45F6-A57F-5ABD9991F28F）。30D016F9-3734-4E33-A861-5E7D899E18F3;FAE04EC0-301F-11D3-BF4B-00C04F79EFBCc. 在最后一个 Import 节点 （Microsoft.CSharp.targets）中，替换ProjectExtensions 节点： 所有的属性都是必需的，缺少任何一个，项目将不能在VSTA中被加载。4. 在 TemplateProject 的解决方案文件夹中添加一个名为 manifest.xml 的XML文件： 5. 打开命令提示符并定位到 TemplateProject 解决方案的文件夹， 执行下列命令：%ProgramFiles(x86)%Microsoft SDKsVSTA11.0ToolsTemplateGenerator.exe /manifest:manifest.xml /output:template.vstax此命令将创建的模板文件 template.vstax 。注意： 你可以在 %ProgramFiles(x86)%Microsoft SDKsVSTA11.0Tools 文件夹中找到可扩展标记语言架构文件 （VstaTemplateManifestSchema.xsd） 。这个文件包含了元素和属性的说明。 清单文件允许多个模板被指定和打包成一个VSTAX文件。从模板创建的项目为了从你的VSTAX 创建一个VSTA 项目，你必须添加少量的代码。在 Visual Studio完成以下操作：1. 添加 VSTAX 文件到你的项目，并将其 复制到输出目录 然后把属性设置为 始终复制 。2. 在窗体中添加一个按钮控件并命名为“新建”，然后为这个按钮控件添加一个事件。3. 向这个事件中添加以下代码：private VSTA.Project _project;private void button2_Click(object sender, EventArgs e) if (_session = null | _project != null) /错误处理 return; var storage = VSTA.ProjectStorage.CreateStorageFromTemplate(template.vstax, csaddin, VSTASample, null); _project = _session.LoadProject(storage);注意： 除了标准的Visual Studio 通配符（如 $safeprojectname$ ），VSTA 还支持通过 CreateStorageFromTemplate 方法向字典中添加键-值对的方法添加自定义通配符。键和值应该按照以下格式配对：“$key$”, “value” 当你用模板创建项目时，生成 SNK 文件需要你的计算机安装有 .NET Framework SDK 。保存并加载项目为了保存并从文件加载项目，你必须首先创建一个类来实现 VSTA 的 IProjectStorage 接口。 IProjectStorage 是一种可以通过名称查找任何项目并返回一个流的简单的机制，它就像一个二元的表或虚拟文件系统一样。 一个 IProjectStorage 和一个项目对应，但在一个以上项目中并不保证项目名称是唯一的。下面的例子在一个 MyProjectStorage 类中实现了 IProjectStorage 接口。在 Visual Studio完成以下操作： 1. 在你的项目中添加一个名为“MyProjectStorage” 的类。2. 添加以下语句： using VSTA = Microsoft.VisualStudio.Tools.Applications;3. 用文件系统实现IProjectStorage 接口作为你的所有项目的一个备份存储： class MyProjectStorage : VSTA.IProjectStorage string _rootDirectory; public MyProjectStorage(string pathRoot) _rootDirectory = pathRoot; public bool ItemExists(string itemName) string fileName = System.IO.Path.Combine(_rootDirectory, itemName); return System.IO.File.Exists(fileName); public System.IO.Stream OpenItem(string itemName, bool writeAccess) string fileName = System.IO.Path.Combine(_rootDirectory, itemName); System.IO.FileMode mode; if (writeAccess) mode = System.IO.FileMode.OpenOrCreate; else mode = System.IO.FileMode.Open; return System.IO.File.Open(fileName, mode); 4. 在窗体中添加一个按钮控件并命名为“保存”，然后为这个按钮控件添加一个事件。5. 向这个事件中添加以下代码： if (_project != null) MyProjectStorage outputProject = new MyProjectStorage(ProjectName); _project.Save(outputProject); 当用户在窗体中单击“保存”按钮时该项目及其所有内容将被保存到应用程序的当前工作目录下的名为“ProjectName” （项目名称）的文件夹中。如果当前工作目录下不存在名为“ProjectName” （项目名称）的文件夹和“Properties”（属性）的文件夹，你必须先创建它们。注意：保存的数据虽然能被像文本一样的阅读，但是数据的格式和编码取决于 VSTA 的实现方法并可能会改变。通过VSTA保存的数据对于宿主应用程序来说都应该视为是“不透明”的。VSTA项目只能通过托管API（ Microsoft.VisualStudio.Tools.Applications 或非托管API）打开。完成并运行项目在创建完项目后，你需要用 BinaryManager 类编译和加载加载项。1. 在窗体中添加一个按钮控件并命名为“运行”，然后为这个按钮控件添加一个事件。2. 在你的窗体中添加以下语句：using System.IO;using System.Reflection; 3. 向这个事件中添加以下代码：private void button3_Click(object sender, EventArgs e) if (_project = null) /错误处理 return; var binaryManager = _project.BinaryManager; / 寻找输出程序集的二进制项目和它的 .pdb 文件。 string assemblyName = binaryManager.AssemblyName; string pdbName = Path.GetFileNameWithoutExtension(assemblyName) + .pdb; VSTA.BinaryItem assemblyItem = null; VSTA.BinaryItem pdbItem = null; foreach (VSTA.BinaryItem item in binaryManager.GetBinaryItems() string itemName = item.Name; if (String.Equals(itemName, assemblyName, StringComparison.OrdinalIgnoreCase) assemblyItem = item; if (pdbItem != null) break; else if (String.Equals(itemName, pdbName, StringComparison.OrdinalIgnoreCase) pdbItem = item; if (assemblyItem != null) break; if (assemblyItem = null) /错误处理 return; / 获得程序集的 byte。 Stream assemblyStream = assemblyItem.GetStream(); byte assemblyBytes = new byteassemblyStream.Length; assemblyStream.Read(assemblyBytes, 0, assemblyBytes.Length); / 获得 .pdb 的 byte。 Stream pdbStream = pdbItem.GetStream(); byte pdbBytes = new bytepdbStream.Length; pdbStream.Read(pdbBytes, 0, pdbBytes.Length); / 加载源程序集。 Assembly assembly = Assembly.Load(assemblyBytes, pdbBytes); / 寻找加载类。 Type addInType = assembly.GetTypes().FirstOrDefault(t) = t.Name = AddIn); if (addInType = null) /错误处理 return; / 寻找 init 方法。 MethodInfo initMethod = addInType.GetMethod(Init); if (initMethod = null) /错误处理 return; /初始化加载项 initMethod.Invoke(null, null);注意： 提供的示例是说明性的，并不详尽。例如，集成商也许想让加载项在被附加在宿主应用程序进程中或运行在一个单独的进程之间切换。 这个示例中加载了程序集和它的符号，这仅仅只需要支持调试所以不需要单纯的运行时脚本。调试项目为了在IDE中调试项目，宿主应用程序必须实现 VSTA.IExternalDebugHost 接口。这个接口允许IDE通知宿主应用程序加载和卸载插件运行时的断点。 下列代码演示了如何实现 VSTA.IExternalDebugHost 接口： internal class ExternalDebugHostImpl: VSTA.IExternalDebugHost private Process _loaderProcess; private static ExternalDebugHostImpl _instance = null; public static ExternalDebugHostImpl Instance get if (_instance = null) _instance = new ExternalDebugHostImpl(); return _instance; private Process CreateHostingProcess(string projectId) Process hostingProcess = null; /设置进程的属性并创建进程。 /返回创建的进程。 return hostingProcess; /Interface methods implementation uint VSTA.IExternalDebugHost.OnBeforeDebugStarting(string projectId) /检查 projectId 是否有效。 /创建一个外部宿主进程，用于加载项的调试。 _loaderProcess = CreateHostingProcess(projectId); /如果外部调试主机进程创建成功，返回到此进程。 if (_loaderProcess != null) return (uint)_loaderProcess.Id; else /如果出现错误，抛出一个异常。 throw new InvalidProgramException(); void VSTA.IExternalDebugHost.OnDebugStarting(string projectId) /确保相同的 projectId 已经开始调试。 /告诉外部调试宿主进程开始运行加载项的程序代码。 void VSTA.IExternalDebugHost.OnDebugStopping(string projectId) /当调试停止/完成时执行必要的清理工作。 try if (!_loaderProcess.HasExited) _loaderProcess.Close(); if (_loaderProcess.ExitCode != 0) /执行适当的的操作。 /当停止调试时执行附加清理。 catch void VSTA.IExternalDebugHost.OnDebugAttachFailed(string projectId) /当调试失败时执行的附加清理。 try if (!_loaderProcess.HasExited) _loaderProcess.Close(); if (_loaderProcess.ExitCode != 0) /执行适当的的操作。 /当失败时执行的附加清理。 catch 为了合理地配置子会话和相应的用于调试的 IDE 实例，宿主应用程序必须通过 ExternalDebugHostImpl 的一个实例创建 SessionManager 类。_sessionManager = VSTA.SessionManager.Create( MyHostApp, new Dictionary() VSTA.SessionManagerOptions.Names.ExternalDebugHost, ExternalDebugHostImpl.Instance );之后， SessionManager 通过执行IExternalDebugHost 方法被创建，宿主应用程序可以使用在Project 类中的 API启动和停止调试。1. 在窗体中添加一个按钮控件并命名为“开始调试”，然后为这个按钮控件添加一个事件。2. 在你的窗体中添加以下语句：using System.IO;using System.Reflection; 3. 向这个事件中添加以下代码： private void button4_Click(object sender, EventArgs e) if (_project = null) /错误处理 return; /要求IDE启动调试 _project.StartDebugging();4. 在窗体中添加一个按钮控件并命名为“停止调试”，然后为这个按钮控件添加一个事件。5. 向这个事件中添加以下代码： private void button5_Click(object sender, EventArgs e) if (_project = null) /错误处理 return; /要求IDE停止调试 _project.StopDebugging();注意： 此文档中的编译和运行示例已经包含了怎样加载加载项的程序集和它的符号。实际上，这些代码并未包含在调试这一节。有关创建加载项的方法，请看例子。 当你创建一个 SessionManager 类的实例时，你可以控制用户是否能从IDE开始调试：/To enable debugging from IDE_sessionManager = VSTA.SessionManager.Create( MyHostApp, new Dictionary() VSTA.SessionManagerOptions.Names.IdeDebuggingEnabled, true );/To disable debugging from IDE_sessionManager = VSTA.SessionManager.Create( MyHostApp, new Dictionary() VSTA.SessionManagerOptions.Names.IdeDebuggingEnabled, false );关闭你的项目你可以调用 Dispose 方法结束一个带有 SessionManager 的会话或 项目 。1. 在你的窗体中添加以下语句：using System.ComponentModel;2. 为了 MyVSTAHost 项目能够提供清理功能，在窗体中添加以下方法：protected override void OnClosing(CancelEventArgs e) if (_project != null) _project.Dispose(); _project = null; if (_project != null) _session.Dispose(); _session = null; if (_project != null) _sessionManager.Dispose(); _sessionManager = null; 这将会让窗体在关闭时释 Project 、 Session 和 SessionManager 类的实例。更多VSTA 有两种线程模式： 单线程模式 （STA）和多线程模式（MTA）。你必须配置 VSTA 以使用正确的线程模式。使用 STA：_sessionManager = VSTA.SessionManager.Create( MyHostApp, new Dictionary() VSTA.SessionManagerOptions.Names.InvokeOnMainThread, true );使用 MTA：_sessionManager = VSTA.SessionManager.Create( MyHostApp, new Dictionary() VSTA.SessionManagerOptions.Names.InvokeOnMainThread, false );从 Visual Studio 2008 Tools for Applications更新项目使用了以前版本的VSTA的集成商也许想把现有代码迁移到Visual