Walkthrough: Creating and Updating an In-Process Host

Article
11/16/2012

This walkthrough demonstrates how to create an in-process host and add it to your project. An in-process host enables you to customize the project system. For example, you might want to enable macro recording in the integrated development environment (IDE) when your project template is open.

An in-process host is an optional addition to your project template. You can specify whether you want the in-process host to run in the Visual Studio Tools for Applications IDE, in Visual Studio, or in both.

This walkthrough shows you how to run an in-process host when a project is opened in the Visual Studio Tools for Applications IDE.

In this walkthrough you will write code to create a new button that inserts a method into your project template code file. This walkthrough illustrates the following tasks:

Creating an in-process host for your project template.
Adding the in-process host to the global assembly cache.
Adding the in-process host to the registry.
Adding the in-process host to a project template.
Updating the ShapeAppCSharp host registration.
Updating the in-process host code.

Prerequisites

You need the following components to complete this walkthrough:

Visual Studio 2008.
Visual Studio Tools for Applications installed on the computer. For information about how to install Visual Studio Tools for Applications, see Installing Visual Studio Tools for Applications.
Access to the ShapeAppBasicCSharp sample application.

Setting Up the ShapeAppBasicCSharp Sample Application

Before you begin creating the in-process host, build and run the ShapeAppBasicCSharp sample application.

To build and run the ShapeAppBasicCSharp sample

Follow the instructions in How to: Build and Run the ShapeAppBasicCSharp Sample.

Creating the In-Process Host

An in-process host is a class that implements the IInProcessHost interface in an assembly. You add a reference to this assembly to your project template. The first step in creating an in-process host is to add a class library to your solution and then add some required references to the project. You then implement the IInProcessHost interface in the new class.

To create an in-process host in Visual Studio

Start Visual Studio.
On the File menu, point to New, and then click Project.

The New Project dialog box appears.
In the Project types pane, expand Visual C#, and click Windows.
In the Templates pane, click Class Library.
In the Name box, type IPHExample.
In the Location box, type drive:\ShapeAppSamples.
Clear the Create directory for solution check box.
Click OK.

The new project appears in Solution Explorer.
In Solution Explorer, select the Class1.cs file and rename it IPH.cs.
In Solution Explorer, right-click References under the IPHExample project and then click Add Reference.

The Add Reference dialog box opens.
On the .NET page, select the following assemblies and then click OK:
- EnvDTE
- Microsoft.VisualStudio.CommandBars
- Microsoft.VisualStudio.Tools.Applications.DesignTime.v9.0

The in-process host needs access to the DTE property of the HostAdapter so that it can monitor events in the project system. To provide access, add the IInProcessHost interface members to your class, and then implement the SetAdapter method.

To implement IInProcessHost

In Solution Explorer, right-click the IPH.cs file, and then click View Code.

Add the following using statements to the top of the code file.

using Microsoft.VisualStudio.Tools.Applications.DesignTime;
using Microsoft.VisualStudio.Tools.Applications.DesignTime.Interop;
using Microsoft.VisualStudio.CommandBars;
using System.CodeDom;
using EnvDTE;

Replace the class declaration with the following code.
```
public class IPH : IInProcessHost
{
}
```

Add the following code to the IPH class to implement SetAdapter. This code calls a method that adds a button to the toolbar, and creates an event handler for the button's Click event.

private HostAdapter iPHhostAdapter;
CommandBarEvents commandBarControlEvents;

public void SetAdapter(IVstaHostAdapter newHostAdapter)
{
    CommandBarControl commandBarControl;

    iPHhostAdapter = (HostAdapter)newHostAdapter;

    commandBarControl = AddButtonToStandardToolbar(
        iPHhostAdapter);
    commandBarControlEvents = (EnvDTE.CommandBarEvents)
        iPHhostAdapter.DTE.Events.get_CommandBarEvents(
        commandBarControl);
    commandBarControlEvents.Click += new
        _dispCommandBarControlEvents_ClickEventHandler(
        commandBarControlEvents_Click);
}

Add the following method to add the button to the Standard toolbar in the IDE.

private CommandBarControl AddButtonToStandardToolbar(HostAdapter
    hostAdapter)
{
    CommandBars commandBars;
    CommandBar standardCommandBar;
    CommandBarControls commandBarControls;
    CommandBarControl commandBarControl;
    CommandBarButton commandBarButton;

    commandBars = (CommandBars)hostAdapter.DTE.CommandBars;
    standardCommandBar = commandBars["Standard"];

    commandBarControls = standardCommandBar.Controls;
    commandBarControl = commandBarControls.Add(
        MsoControlType.msoControlButton, 1, null, 1, false);
    commandBarButton = (CommandBarButton)commandBarControl;

    commandBarButton.Visible = true;
    commandBarButton.Caption = "Insert Method";
    commandBarButton.OnAction = "InsertMethod";
    commandBarButton.FaceId = 288;

    return commandBarControl;
}

Add the following event handler for the Click event of the button. When the user clicks this button, a method is added to the code file.

private void commandBarControlEvents_Click(object CommandBarControl,
     ref bool Handled, ref bool CancelDefault)
{
    CodeMemberMethod codeMemberMethod = new CodeMemberMethod();
    codeMemberMethod.Name = "ReturnString";
    codeMemberMethod.ReturnType = new
        CodeTypeReference("System.String");
    codeMemberMethod.Parameters.Add(new
        CodeParameterDeclarationExpression(
        "System.String", "text"));
    codeMemberMethod.Statements.Add(new
        CodeMethodReturnStatement(new
        CodeArgumentReferenceExpression("text")));
    this.iPHhostAdapter.ProjectHostItems[0].AddMethod(
        codeMemberMethod);
}

On the Build menu, click Build Project.

The IPHExample.dll file is created in the \bin\Debug directory of your solution.

Now that you have the in-process host assembly, you must sign it with a strong name and add it to the global assembly cache. You then register the assembly. After the assembly is in the global assembly cache and registered, you can add it to a project template.

Adding the In-Process Host to the Global Assembly Cache

Only signed assemblies can be added to the global assembly cache; therefore, you must first sign the in-process host with a strong name.

To sign the in-process host

Right-click the IPHExample project in Solution Explorer, and then click Properties.

The Project Designer opens in Visual Studio.
On the Signing page, select the Sign the assembly check box.
Click the drop-down list box under Choose a strong name key file, and then click New.
In the Create Strong Name Key dialog box, type IPHKey in the Key file name box, clear the Protect my key file with a password check box, and click OK.

A key file named IPHKey.snk is created.
Save the project and close the Project Designer.
On the Build menu, click Rebuild Solution.
Click Save All and save the IPHExample project to the drive:\ShapeAppSamples directory.

Use the Global Assembly Cache tool (Gacutil.exe) to add the IPHExample assembly to the global assembly cache and to obtain the public key token of the assembly. The public key token represents the public key under which the application is signed. You will need the public key token when you register the assembly.

To add the signed in-process host DLL to the global assembly cache

Open the Visual Studio 2008 Command Prompt window. If you are using Windows Vista as your operating system, start the Visual Studio 2008 Command Prompt window by using the Run as Administrator option.
Change directories to the location of Gacutil.exe on your development computer. For example, you might change directories to %ProgramFiles%\Microsoft Visual Studio 8\SDK\v2.0\bin.
Type the following at the command prompt and then press ENTER:
```
gacutil /i C:\ShapeAppSamples\IPHExample\bin\Debug\IPHExample.dll
```
The DLL is added to the global assembly cache.
Verify that the IPHExample.dll file is in the global assembly cache by locating it in %SYSTEMROOT%\Assembly\GAC.
Type the following at the command prompt and then press ENTER:
```
gacutil /l IPHExample
```
The output displays the name of the DLL, version number, culture, and public key token. Save this information because you will enter it into the registry in the next section.

Adding the In-Process Host to the Registry

Visual Studio Tools for Applications requires that the in-process host be added to the registry as an extra security measure against running untrusted code when a project template is opened. To add it to the registry, create a GUID for the in-process host and then register the IPHExample.dll file using the GUID as the registry key.

To create a GUID for the in-process host

Start the GUID generation tool called Guidgen.exe, which is located in the directory %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\Tools\.
In the Create GUID dialog box, select 4. Registry format, and then click New GUID.
Click Copy, and then click Exit.

The generated GUID is copied to the Clipboard.
Paste the GUID into the IPHExample code file as a comment. You will enter this information into the registry in the next section.

After you have created a GUID for the in-process host, you can use it to uniquely identify the assembly in the registry.

To add the in-process host to the registry

Open the Visual Studio 2008 Command Prompt window. If you are using Windows Vista as your operating system, start the Visual Studio 2008 Command Prompt window by using the Run as Administrator option.
Type Regedit, then press the ENTER key.

The Registry Editor opens.
Create a new registry key named VSTA as follows:
- On 32-bit operating systems, right-click HKEY_LOCAL_MACHINE\Software\Microsoft\VSTAHostConfig\ShapeAppCSharp\2.0, point to New, and then click Key.
- On 64-bit operating systems, right-click HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\VSTAHostConfig\ShapeAppCSharp\2.0, point to New, and then click Key.
A new registry key is added.
Change the name of the new registry key to VSTA.
Create another registry key under VSTA and name it InProcHost.
Create another registry key under the InProcHost key.
Change the name of the new registry key to the GUID that you created earlier. You can copy and paste it from your code file.
Right-click the new GUID registry key, point to New, and then click String Value.
Rename the new value Assembly.
Right-click the Assembly key and then click Modify.
In the Value data field of the Edit String dialog box, add the assembly name, version, culture, and public key token that you got in the previous section when you ran Gacutil.exe. For example:

iphexample, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b0a84c23d7c3462e

Note

Replace the above data with data from your assembly.
Right-click the GUID registry key, point to New, and then click String Value.
Rename the new value FullClassName.
Right-click FullClassName, and then click Modify.
In the Value data field of the Edit String dialog box, add the class name of your in-process host qualified by its namespace.
```
IPHExample.IPH
```
Close the Registry Editor.
Save and close the in-process host solution.

Adding the In-Process Host to a Project

To make the in-process host available in every ShapeAppBasicCSharp add-in project, add it to the project template. For more information about how to create project templates, see Creating Project Templates (Visual Studio Tools for Applications).

Note

You can also add an in-process host to a project by using the Projectgen.exe wizard. For more information about the wizard, see Walkthrough: Creating a Project Template Using the Project Template Wizard.

Projects identify associated in-process hosts by checking whether a GUID for the in-process host is listed in the project file.

To add the in-process host to a project file

Open the ShapeAppCSharpAppAddInProject.csproj file for Visual C# in a text editor such as Notepad. The ShapeAppCSharpAppAddInProject.csproj file is located in the .zip file at drive:\ShapeAppSamples\ShapeAppBasicCSharp\templates\CSharp\ShapeAppCSharp-AppLevel.zip.

Note

The files in the .zip file are read-only. You must make the changes to a copy of the ShapeAppCSharpAppAddInProject.csproj and save it back to the .zip file.
Add the GUID for the in-process host to the <InProcHost> element under the <HostIdentifier> node.
```
<ProjectClient>
    <HostIdentifier>ShapeAppCSharp</HostIdentifier>
    <InProcHost>{GUID}</InProcHost>
</ProjectClient>
```
Note

Replace the string GUID with the actual GUID you created for the in-process host. Include the braces around the GUID.
Save and close the ShapeAppCSharpAppAddInProject.csproj file, and copy it back to the .zip file.

Updating the ShapeAppCSharp Host Registration

You must update the ShapeAppCSharp host registration by regenerating the host context registry hive. For more information, see Registering the Host Application.

To update the ShapeAppCSharp host registration

Click Start, and then click Run.
Type regedit, and then press ENTER.
In the Registry Editor, navigate to the host context registry hive for ShapeAppCSharp:
- On 32-bit platforms:
  
  HKEY_LOCAL_MACHINE\Software\Microsoft\VSTAHost\ShapeAppCSharp\9.0
- On 64-bit platforms:
  
  HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\VSTAHost\ShapeAppCSharp\9.0
Delete the 9.0 key under the ShapeAppCSharp key.
Open the Visual Studio 2008 Command Prompt window. If you are using Windows Vista as your operating system, start the Visual Studio 2008 Command Prompt window by using the Run as Administrator option.
Change directories to %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE.
Type the following command at the command prompt and press ENTER to register the templates.
```
vsta /hostid ShapeAppCSharp /setup
```

Testing the In-Process Host

Test the in-process host by creating a ShapeAppCSharpAppAddIn add-in project and then clicking the new button.

To test the in-process host

Open the Visual Studio 2008 Command Prompt window. If you are using Windows Vista as your operating system, start the Visual Studio 2008 Command Prompt window by using the Run as Administrator option.
Change directories to %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE.
Type the following command at the command prompt and press ENTER.
```
vsta /hostid ShapeAppCSharp
```
The Visual Studio Tools for Applications IDE opens.
On the File menu, click New Project.
In the Project Types pane, select Visual C#.
In the Templates Pane, select ShapeAppCSharp-AppLevel, and then click OK.
A solution named ShapeAppCSharpAppAddIn1 opens in the Code Editor.

A new button (Insert Method) appears as the first button on the Standard toolbar.
In Solution Explorer, right-click AppAddIn.cs, and then click View Code.

The AppAddIn class appears in the Code Editor.
On the Standard toolbar, click the Insert Method button.

A method named ReturnString is added to the AppAddIn class of the project.

Making Changes to the In-Process Host Code

If you want to make changes to your in-process host code after you have added it to the global assembly cache and the registry, you do not have to repeat all of the steps described above. Instead, rebuild your in-process host project, remove the outdated in-process host from the global assembly cache, and then add the new in-process host to the global assembly cache.

To revise the in-process host code

Open the IPHExample solution in Visual Studio.
Change the name of the method from ReturnString to StringReturn.
```
codeMemberMethod.Name = "StringReturn";
```
On the Build menu, click Build Project.

The IPHExample.dll file is saved in the \bin\Debug directory of your solution.
Open the Visual Studio 2008 Command Prompt window. If you are using Windows Vista as your operating system, start the Visual Studio 2008 Command Prompt window by using the Run as Administrator option.
Change directories to %ProgramFiles%\Microsoft Visual Studio 8\SDK\v2.0.
Uninstall the IPHExample assembly from the global assembly cache by typing the following command at the command prompt, and then pressing ENTER.
```
gacutil /u IPHExample
```
The IPHExample assembly is removed from the global assembly cache.
Add the revised IPHExample assembly to the global assembly cache by typing the following command at the command prompt.
```
gacutil /i %SYSTEMDRIVE%\ShapeAppSamples\IPHExample\bin\Debug\IPHExample.dll
```
The DLL is added to the global assembly cache.
Open a Command Prompt window and change directories to drive:\ShapeAppSamples\ShapeAppBasicCSharp\Templates\CSharp.
Type the following command at the command prompt to open the ShapeAppCSharp add-in in the IDE.
```
vsta /hostid ShapeAppCSharp
```
Create a new ShapeAppCSharp-AppLevel project in Visual C# and open AppAddIn.cs in code view.
Click the Insert Method button in the IDE.

The name of the method that is inserted is now StringReturn.

Next Steps

This walkthrough shows you how to create an in-process host for your project file so that you can extend the project functionality. As a next step, you might want to integrate the IDE into your host application. For more information, see Walkthrough: Incorporating the IDE for a Managed Object Model.

Share via