In-Process Host Sample: Kill
VSTA Process with Host
Overview:
This document provides information and a walkthrough for the
IPH Sample: Kill VSTA Process with Host.
This sample shows how to use an In-Process Host (IPH) to kill a VSTA.exe
process that lingers when the host is “hard killed”. The host used in this sample is
ShapeAppCSharp and templates using the IPHs are provided for
ShapeAppAdvancedCSharp (VSTA v 1) and ShapeAppMacroRecordingCSharp (VSTA v 2). IPHs are VSTA version specific, so IPHs are
included for both VSTA versions 1 and 2.
These IPHs can easily be adapted for use with any host.
Introduction:
This IPH is designed in response the problem of a VSTA.exe
process remaining running after the associated host crashes or is “hard killed”
(stopped from the debugger or Task Manager).
The host application which brings up the VSTA DTE should have code that
handles the VSTA shutdown gracefully when the host shut downs. Unfortunately, when the host crashes or is
“hard killed” the code to bring down the VSTA DTE is not reached. This IPH checks for the scenario of the VSTA
DTE running while the host is not and responds by prompting the user to save
and then killing the VSTA.exe process.
By design, this IPH should only be used for project
templates used in “tightly” integrated scenarios. Using this IPH in templates which are used
during “loose” integration scenarios will result in the projects terminating
because an instance of the host is not running.
In other words, templates using this IPH and projects based on these
templates should only be loaded programmatically by the host.
For this IPH, strings are used as search parameters for the
host. Any instance of the host, or any
host which has a VSTA.exe process open, may satisfy the search criteria. This could lead to the scenario of the VSTA.exe
processes staying open until the last host with a VSTA.exe process is killed.
A quick look at IPHs:
For information on IPHs please refer to the VSTA SDKs, they
provide detailed information and comprehensive walkthroughs which show 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.
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.
What is included with
this sample:
This sample includes all files necessary to use the IPH with
any host, or to simply update the ShapeApp samples. These files include:
1)
The IPH_Kill_VSTA_With_Host_v# projects. These are the projects that will be
associated with the templates as an IPH.
Both are written in C# with Visual Studio 2005 and may be opened with
Visual Studio 2005 or 2008.
2)
The IPH_Kill_VSTA_With_Host_v# registration files. These files register the IPH for
ShapeAppCSharp for VSTA versions 1 or 2.
3)
The ShapeAppCSharp_Macro_v# templates (C#) and
template descriptor files. The
ShapeAppCSharp_Macros_v1.zip file is for use with ShapeAppAdvancedCSharp for
VSTA v 1, and The ShapeAppCSharp_Macros_v2.zip file is for use with
ShapeAppMacroRecordingCSharp for VSTA v 2.
The only differences between these two templates are the proxy and IPH used. These templates assume that the associated
proxy will be located in the default location of
%SystemDrive%\ShapeAppSamples\<sample> \proxy\bin\Debug\ShapeAppCSharpProxy.dll.
4)
IPH_Kill_VSTA_With_Host Walkthrough.doc.
Walkthrough to use
this IPH in ShapeAppCSharp:
This walkthrough assumes that the ShapeAppAdvancedCSharp or
ShapeAppMacroRecordingCSharp sample is installed in it’s default location, the
corresponding setup file has been run so that the ProjectTemplatesLocation is
%SystemDrive%\ShapeAppSamples\ShapeApp[Advanced or MacroRecording]\templates,
and that the ShapeApp sample and proxy have been built.
1)
Extract the IPH_ Kill_VSTA_With_Host_v# sample
projects to %SystemDrive%\ VSTA\Summit Software\Samples (the IPHs will work
from any location).
2)
Open and build the IPH_ Kill_VSTA_With_Host_v# project. The post build event will install the
assembly in the GAC.
3)
Copy the corresponding template zip file to the CSharp
ProjectTemplatesLocation. This should be
%SystemDrive%\ShapeAppSamples\<sample>\Templates\CSharp.
4)
Run the registration file, IPH_ Kill_VSTA_With_Host_v#.reg,
by double clicking it. This will add the
IPH to the registries for VSTA version 1 or 2.
5)
From the Visual Studio Command Prompt, run the
command “vsta /hostid ShapeAppCSharp /setup”.
This extracts the templates added above.
6)
Set up the ShapeApp sample to use the new
templates for the macro project. Remove
any existing macro files from %MyDocuments%\ShapeAppCSharp to force ShapeApp to
create a new macro project. In the
ShapeApp sample, locate the CreateNewMacroProject method in the extension or
VstaDesignTimeIntegration class. Change
the second line of this method, where the macroTemplatePath variable is set, to
use the new template ShapeAppCSharp_Macro_v#.
7)
Test the IPH.
·
Open the Task Manager and verify there are no instances
of the VSTA.exe process running.
·
Keeping
the Task Manager open, run the ShapeApp sample and launch the IDE (with
Alt+F11).
·
Verify in the Task Manager that there is now a VSTA.exe
process running.
·
Kill the ShapeApp application by stopping the debugger. For VSTA v 2, close the ShapeApp solution
file.
·
Verify in the Task Manager that the VSTA.exe
process is still running.
·
Within a few seconds a message box stating that
VSTA is shutting down because the host is no longer running should appear. Click OK.
·
Verify in the Task Manager that the VSTA.exe
process is no longer running.
·
To test the IPH with a stand alone exe, kill the
application through Task Manager.
* For ShapeAppMacroRecordingCSharp, if
the macro project fails to build see the ShapeAppMacroRecordingCSharp-
common problems and workarounds blog on our website.
Walkthrough to use
this IPH in any host:
This sample may be modified to work with any host by
following these steps:
1)
Extract the IPH_ Kill_VSTA_With_Host_v# sample
project to %SystemDrive%\ VSTA\Summit Software\Samples (the IPH will work from
any location).
2)
Open and build the IPH_ Kill_VSTA_With_Host_v#
project. The post build event will
install the assembly in the GAC.
3)
Generate a new GUID with the GuidGen tool
located at %Program Files%\Microsoft Visual Studio #\Common7\Tools. Use option 4, Registry Format, and copy the
new GUID, it will be used to update the registration file
4)
Update the registration file by replacing
ShapeAppCSharp with the new hostID and the included GUID with the GUID
generated in step 4 above.
5)
Run the updated registration file, IPH_ Kill_VSTA_With_Host_v#.reg,
by double clicking it. This will add the
IPH to the registries for VSTA version 1 or 2.
6)
Update the IPH project that corresponds with the
versions of VSTA in use. In the
SetAdapter method, set the searchProcs variable to the host’s running
application name (like ShapeAppCSharp.exe).
Adjust the dueTime and period variables if desired, dueTime is the
length to wait before checking starts, period is the length of time between
checks, both in milliseconds.
For VSTA v 1, the value
“vstaremoteprocess” for the searchROT variable will work with any host, but can
be changed if desired. For VSTA v 2, no
object like “vstaremoteprocess” is registered in the ROT. If your host app registers an object in the
ROT and has a unique name, use part or all of the name for the searchROT
variable. Otherwise, search the local
processes a second time, using the variable searchProcs2, for an instance of
your host open in Visual Studio. This
should have a name containing something like “ShapeAppCSharp.vshost.exe”.
Build the project, the post build
event will install the assembly in the GAC.
7)
Create a new template with ProjectGen and
specify the IPH on the 3rd screen.
For existing templates, update them through ProjectGen by using the
existing project template descriptor file and specify the IPH on the 3rd
screen. To update a template without an
existing template descriptor file, edit the csproj or vsproj file with a text
editor and add the GUID to the InProcHost element under the HostIdentifier
node, replace the original template with the updated zip file (see SDK for more
information).
8)
From the Visual Studio Command Prompt, run the
command “vsta /hostid <hostID> /setup”.
This extracts the templates created or updated above.
9)
Set up the host to use the new templates for the
macro project. Remove any existing macro
files to force the host to create a new macro project. In the host, locate the equivalent of the CreateNewMacroProject
method in the extension or VstaDesignTimeIntegration class. Change the line where the macroTemplatePath
variable is set, to use the template created or updated above.
10)
Test the IPH.
Follow the same testing instructions listed above.