Dynamically Creating and Modifying Host Items and Host Objects in an Add-in Project

Article
11/16/2012

You can add code to the host application that dynamically modifies the object model of an add-in project that is open in the Visual Studio Tools for Applications IDE. The host application can raise an event when a developer creates an instance of an item in the host application, for example, a document or a form, or an object, such as page or a control. Your code can handle the event and add a corresponding host item or host object to the open add-in project. When you add a host item or host object, you generate code in the project that the developer can use to access the corresponding item or object in the host application.

Host Items

A host item is a class that provides a starting point where add-in developers can write their code. Host items are also containers for host objects. For example, a project can contain a host item named Document1 that developers would use to customize a document in the host application. The document item can also contain objects such as range objects and controls.

Host items appear as partial classes that are split between a user code file and a designer code file. Developers add code to the partial class that is in the user code file to access the methods and properties that are defined in the host item.

Host items derive from entry point classes in the proxy assembly. An entry point is a proxy type that provides direct access to an item in the host application. For more information, see Defining Entry Points and Other Proxy Changes.

Accessing Host Items in an Add-in Project

Every project contains a collection of host items. Use this collection to add and remove host items in the project. You access the collection through the Visual Studio Tools for Applications IDE host adapter. The host adapter is an object that implements the IVstaHostAdapter interface. This object provides your host application with access to the Visual Studio Tools for Applications IDE and project system. You can get this object from code in the host application, or from an in-process host.

Accessing the Host Adapter from Code in the Host Application

To get the host adapter, you must have an object of type Project. Get the IVstaHostAdapter object by calling the Extender property of the Project class. For more information, see How to: Add and Remove Host Items in an Add-in Project.

For a code example that demonstrates how to get a Project, see Walkthrough: Adding Host Items and Host Objects to an Add-in Project.

You can lose some host adapter events if you use this procedure. However, you can load the events separately by using the HostAdapterEventsWrapper class. For more information, see Loading Host Adapter and Host Item Events.

Accessing the Host Adapter from an In-Process Host

You can access the host adapter from the SetAdapter method of an in-process host.

When you create an in-process host, you implement the SetAdapter method of the IInProcessHost interface. This method receives an object that implements the IVstaHostAdapter interface as a parameter. For more information, see Dynamically Creating and Modifying Host Items and Host Objects in an Add-in Project.

Adding Host Items to a Host Item Collection

Use the host adapter to get a collection of host items in the project. Add and remove host items in the collection in response to events that are raised when the developer creates or removes an item in the host application. For more information, see How to: Add and Remove Host Items in an Add-in Project.

Changing the Display Name of a Host Item

The display name of a host item helps the add-in developer keep track of how an item that appears in the UI of the host application maps to a host item that appears in the project. The display name of the host item appears in parentheses next to the name of the code file.

When the add-in developer changes the name of an item in the host application UI, your code can handle the event that is raised and change the display name of the host item in the project. For example, if the add-in developer changes the name of a drawing from "Drawing1" to "MyDrawing", then your code could change the name of the host item from "Drawing1.cs" to "Drawing1.cs (MyDrawing)".

For the procedure and a code example, see How to: Change the Display Name of a Host Item.

Host Objects

A host object is an instance of a class that can be accessed only by using a property or method in the host item that contains the object. For example, in the ShapeApp sample applications, the Drawing1 host item might contain one or more Shape objects. The developer could use the Shape property of the Drawing1 class to get the Shape object.

When an add-in developer adds an object in the host application, your code can add a host object to the add-in project. When you add a host object, a field is automatically added to the host item class. Add-in developers can access the host object by using this field. In addition, code that creates an instance of the host object is automatically added to the constructor of the host item class.

When you remove a host object, the field that represents the host object and the code that was added to the constructor of the host item class is automatically removed. For more information, see How to: Add and Remove Host Objects in an Add-in Project.

Loading Host Adapter and Host Item Events

If you use the Extender property of the Project class to get the Visual Studio Tools for Applications host adapter, host adapter and host item events are lost. This happens because the Extender property gets the host adapter by marshalling an object across a COM boundary.

To load the host adapter and host item events, use the following two classes:

HostAdapterEventsWrapper to load host adapter events.
HostItemEventsWrapper to load host item events.

Loading Host Adapter Events

Use the HostAdapterEventsWrapper class if you want to load any of the following events:

The following example uses the HostAdapterEventsWrapper to load the ActivateProjectHostItem event.

private void load_HostAdapter_Events()
{
    // Get the host adapter.
    hostAdapter =   
        (IVstaHostAdapter)project.get_Extender("VSTAHostAdapter2007");

    // Load host adapter events by using the 
    // HostAdapterEventsWrapper class.
    HostAdapterEventsWrapper wrapper = new    
        HostAdapterEventsWrapper(hostAdapter);
    wrapper.ActivateProjectHostItem += new 
        ActivateProjectHostItemEventHandler(wrapper_ActivateProjectHostItem);
}
// Event handler for ActivateProjectHostItem event.
void wrapper_ActivateProjectHostItem(object sender, IActivateEventArgs eventArguments)
{
    // Put event handler code here.
}

Loading Host Item Events

Use the HostItemEventsWrapper class if you want to load any of the following host item events:

The following example uses the HostItemEventsWrapper to load the Changed event.

private void load_HostItem_Events()
{
    // Get the host adapter.
    hostAdapter =   
        (IVstaHostAdapter)project.get_Extender("VSTAHostAdapter2007");
    
    // Get the first host item from the collection of 
    // project host items.
    IVstaHostItem hostItem = 
        this.hostAdapter.ProjectHostItems[0].ProgrammingModelHostItem;
    
    // Load host item events by using the HostItemEventsWrapper class.
    HostItemEventsWrapper wrapper = new 
        HostItemEventsWrapper(hostItem);
    wrapper.Changed += new    
        HostItemChangedEventHandler(wrapper_Changed);
}
// Event handler for the Changed event.
void wrapper_Changed(object sender, IChangedEventArgs eventArguments)
{
    // Put event handler code here.
}