Melody's VSTA Blog : VSTA v 1

Post Build Events in VSTA

Melody — Tue, 19 Feb 2008 18:56:00 GMT

Post build events are very important in VSTA (versions 1 and 2). They are used to install files in the GAC, organize DLL's for add-in discovery, and in VSTA v 2, to rebuild the pipeline.

Here are the files used in post build events by the ShapeApp samples, the commands which run them, and some information about them.

File: InstallInGAC.bat

Description: Used by a proxy to install the proxy assembly in the GAC.

Command: call "$(ProjectDir)InstallInGac.bat" "$(TargetPath)"
Notes: This file changed from VSTA v 1 to VSTA v 2. The VSTA v 1 InstallInGAC.bat file looks for the GACutil tool in %programfiles%\Microsoft Visual Studio 8\SDK\v2.0\Bin\gacutil where Visual Studio 2005 places it. The VSTA v 2 InstallInGAC.bat file looks for the GACutil in %WindowsSDKPath%bin\ (WindowsSDKPath is read from the registry) where Visual Studio 2008 places it. We offer a version, InstallInGAC_0508.bat, which looks in both locations and will work with Visual Studio 2005 and Visual Studio 2008.
Command for our version: Call "$(ProjectDir)InstallInGac_0508.bat" "$(TargetPath)"

File: InstallForVB.bat

Description: Used by a proxy to copy the proxy assembly into the pipeline and rebuild it.
Commands: call "$(ProjectDir)InstallForVB.bat" "$(TargetPath)"
Notes: This file is new for VSTA v 2 and is generally used together with the InstallInGAC file.

File: InstallAddIn.js

Description: Used by add-ins to move the assembly to %My Documents%\<HostID>\AppAddIns in a folder with the same name as the assembly.

Commands: cscript "$(ProjectDir)InstallAddIn.js" "$(TargetPath)" "ShapeAppCSharp\AppAddIns\$(TargetName)"
Notes: In the command above, replace ShapeAppCSharp with the HostID, or the value specified in the registry for the entry UserFilesFolderName. This file is the same for VSTA v 1 and v 2. This post build event moves the add-in assembly to a programatically searchable location, %My Documents%\<HostID>\AppAddIns.

In VSTA v 1, this location is used for the appAddInPath variable which is set in the Connect method and in the LoadAppAddIns method to load add-ins in the extension class.

In VSTA v 2, this location is used for the AppLevelAddInPath variable which is used in the LoadAppLevelAddIns method to load add-ins in the VstaRunTimeIntegration class.

The best way to get add-ins to use this post build event, is to specify it in the template. Unfortunately, there is no way to add the InstallAddIn.js file and post build event through ProjectGen. Instead, the template created by ProjectGen must be manually updated then (re)registered with VSTA. For more information on how to do this, check out my blogs on how to add this post build event, and how to update an existing template.

Using VSTA to extend a host with Office

Melody — Mon, 21 Jan 2008 21:06:00 GMT

VSTA can be used extend a host to use a new technology, like an Office application, without requiring any changes in the host. One benefit of this is that the host is now compatible with any technology that can be accessed by an add-in.

One example of this would be to use an Excel spreadsheet to enter data. We have a simple example of this with ShapeAppCSharp (VSTA v 1 and v 2 samples available here). The VSTA add-in opens an excel spreadsheet and reads in data for shapes to be added to a drawing. This allows Excel to be used as a data entry form to automate the host without making any changes to the host.

To use Office applications in VSTA, add references to the appropriate assemblies. For VSTA v 1, to add a reference to the Excel application, choose the "Microsoft Excel # Object Library" from the COM tab of the Add References window, it should have a path like %ProgramFiles%\Microsoft Office\OFFICE#\EXCEL.EXE. This will add the entries "Excel" and "Microsoft.Office.Core" (which can be removed) under references in the Solution Explorer. When viewed in the Object Browser, the "Excel" entry is identified as Microsoft.Office.Interop.Excel.dll. For VSTA v 2, the Microsoft.Office.Interop.Excel reference is listed on the .Net tab of the Add References window. This change is due to the addition of the office libraries into Visual Studio 2008.

IPH Sample- Kill the VSTA Process With Host

Melody — Fri, 11 Jan 2008 02:53:00 GMT

We have received many support requests in regards to the following scenario: The host application is "hard killed" and the vsta.exe process continues to run. A "hard kill" can occur if the debugger is stopped, or the host application is terminated through the Task Manager. In hard kill scenarios, the host never has the opportunity to shut down VSTA.

The answer to this problem is an In-Host Provider (IPH). VSTA makes In-Host Providers incredibly easy to use and the SDK (v1 and v2) provide excellent documentation and a walkthrough. We now offer an IPH sample which addresses the above scenario.

The IPH Sample- Kill VSTA With Host provides IPHs, registration files, and templates for VSTA v 1 and v 2. The IPHs and registration files are set up for ShapeAppCSharp (VSTA v 1 and v2) and are easily adaptable for any host with either VSTA v 1 or v 2. The templates may be used with ShapeAppAdvancedCSharp (VSTA v 1) and ShapeAppMacroRecording (VSTA v 2). The sample also includes a walkthrough with instructions on how to incorporate the IPH with any host.

Click here to go to the IPH Sample- Kill VSTA With Host download page.

Here is an excerpt from the walkthrough:

A quick look at IPHs:

For information on IPHs please refer to the VSTA SDK, they provide detailed information and a comprehensive walkthrough which shows how to make and use an IPH. Here is a summary explanation of IPHs.

· IPHs are projects written in Visual Studio that implement the IInProcessHostInterface. For VSTA v 1, this interface is defined in Microsoft.VisualStudio.Tools.Applications.DesignTime and includes the method SetAdapter which takes in a HostAdapter. For VSTA v 2, this interface is defined in Microsoft.VisualStudio.Tools.Applications.DesignTime.v9.0 and includes the method SetAdapter which takes in an IVstaHostAdapter.

· IPHs do not have a language requirement.

· IPHs are associated with a project template. This association can be set by using ProjectGen, or editing the csproj or vbproj file (in a text editor like Notepad) of an existing template. All projects created based on the project template will use the IPH.

· Only one IPH can be associated with a template; however, one IPH may be used by multiple templates and hosts.

· IPHs must be registered with the host and in the GAC.

· The IPH runs in the same process as the VSTA DTE and has the same lifetime as the project that the IPH is associated with. Closing the project or the VSTA DTE kills the IPH, opening a different project in the VSTA DTE (only one project can be at a time in the VSTA DTE) kills the IPH.

· An IPH can be set to run with Visual Studio as well as VSTA; however, that is not addressed in this sample.

To use an IPH the following steps must be completed (for more information, see the SDK)

1) Create an IPH project- a project with a class which implements the IInProcessHost interface.

2) Add IPH’s project’s dll to the GAC (IPH must to be strongly signed).

3) Add the IPH to the host’s registry hive. A GUID is required for this step and can be produced using the GuidGen tool. Add the entries for the IPH to the config hive, then delete the context hive and run setup to re-create it.

4) Add the IPH to a project template.

5) Run setup to extract the template.

What this sample does:

This IPH checks the Running Object Table (ROT) and the local processes for an instance of the host and kills the VSTA.exe process if one is not found. The ROT is checked for any VSTA remote process (“…vstaremoteprocess…”). This process is created when the host creates a VSTA v 1 DTE (for an example see the EnsureIDE method of ShapeApp samples) during debugging or when run as a stand alone exe. The local processes are checked for an instance of the host, like “ShapeAppCSharp.exe” or “ShapeAppCSharp.vshost.exe”, which would be created by running the application as a standalone exe or debugging it with Visual Studio. This IPH can be used both during development and for distribution. If an instance of the host or VSTA remote process is not found (i.e. any instance of either) then the IPH prompts the user to save and closes the VSTA DTE.