Share via

So what are these Host Controls you speak of?

  • Article

Host controls are at the heart of the VSTO 2.0 programming model. What are they, how and when do you create them, and what do they do for you?

What is a Host Control?
We provide several host controls in the VSTO 2.0 programming model. For Excel, we provide a NamedRange, XMLMappedRange, and ListObject, and a ChartObject host control. For Word, we provide a Bookmark, an XMLNode, and an XMLNodes host control. These classes are found in the Microsoft.Office.Tools.Excel and Microsoft.Office.Tools.Word name spaces.

As you might have noticed, these host controls seem to correspond to existing objects that are already in the Excel and Word object models. In our world, we call Excel and Word the "host" that is hosting the customization, hence the name host controls.

  • Microsoft.Office.Tools.Excel.NamedRange maps to Microsoft.Office.Interop.Excel.Range (and Microsoft.Office.Interop.Name--subject of a future blog)
  • Microsoft.Office.Tools.Excel.XMLMappedRange maps to Microsoft.Office.Interop.Excel.Range
  • Microsoft.Office.Tools.Excel.ListObject maps to Microsoft.Office.Interop.Excel.ListObject
  • Microsoft.Office.Tools.Excel.ChartObject maps to Microsoft.Office.Interop.Excel.ChartObject
  • Microsoft.Office.Tools.Word.Bookmark maps to Microsoft.Office.Interop.Word.Bookmark
  • Microsoft.Office.Tools.Word.XMLNode maps to Microsoft.Office.Interop.Word.XMLNode
  • Microsoft.Office.Tools.Word.XMLNodes maps to Microsoft.Office.Interop.Word.XMLNodes

Indeed, the seven host controls we provide actually implement these Microsoft.Office.Interop.* interfaces as described above (but they don't say they implement the interface in the type definition for reasons best explained in another post). They wrap an actual instance of an Excel or Word object model object, and so a ListObject host control has all the properties and methods and events that raw ListObject in Excel has.

In addition to providing access to all the underlying functionality of the Excel or Word object being wrapped, host controls also add WinForms data binding support by implementing a new interface in WinForms called IBindableComponent. This means that for the seven host controls I have mentioned above, you can do WinForms style data binding against them.

Furthermore, host controls bubble events that were previously only available at the Worksheet or Document level down to the host control itself. You can therefore have a NamedRange host control corresponding to a particular named range and the handler for the Change event on that host control will only fire when that NamedRange changes.

How and When are these Host Controls created?
Host controls are a great way to give you a programming model based on the contents of the document or template you are creating. For example, if you have a spreadsheet called “Sheet1“ that has a named range called “CustomerName“, a ListObject called “Orders“, and a Chart called “SalesResults“--we will automatically create for you 3 host controls in the programming model we generate for Sheet1. As you continue editing the spreadsheet and adding, deleting, or renaming these named items, we will update the programming model accordingly. So if you add a second ListObject called “Details” we will add another host control called “Details“ to Sheet1 for you.

Now, when you go into the code item for Sheet1 you will be able to type code like:

CustomerName.Value = “John Smith”
Orders.ShowTotals = true
Details.ShowTotals = true
SalesResults.HasLegend = true

CustomerName, Orders, SalesResults, and Details are predeclared for you and hook up to the corresponding items in Sheet1 at runtime without any work from you. You get a bunch of useful objects to write code against without having to figure out how to navigate to these objects through the object model. (This notion of predeclaring things has always been central to VBA and Office programming, so much so that it has an internal name that was often associated with VBA--“The Pre-declared IDE“)

Also as mentioned earlier, you can add an event handler to a host control. For example, I can handle the CustomerName_Changed event which will only fire when the value in the CustomerName named range changes.

What Do Host Controls Do For Me?
You should have a rough idea of this already. There are several big areas:

  1. They promote into your programming model “items of interest“--elements in the document that you have named or that are commonly accessed.
  2. They make Office development feel more like the WinForms “controls on a form“ model. 
  3. They allow you to handle events at the view control level instead of at the document level.
  4. Host control properties can be viewed and changed in the property grid at design time--this isn't the case with other arbitrary Excel and Word OM objects. We've also attributed the properties of our host controls to only display in the property grid the properties that make sense. For example, you'll notice in VBA when you try to view a Worksheet in the property grid that only a subset of all available Worksheet properties are shown in the property grid.
  5. All host controls support simple WinForms data binding--binding to a property. ListObject is a special host control in that it also supports complex data binding.
  6. In some areas we've enhanced the functionality of the host control to solve common problems associated with using the underlying raw Word or Excel OM object. For example, we do some magic so that bookmarks don't get deleted and disappear like they do in Word. For the NamedRange host control we provide both the properties and methods of Excel's range object as well as the properties and methods of Excel's Name object.
  7. However, we haven't changed the basic signature of the host control from what it wraps. You will find that all your code that currently works against a raw range, ListObject, bookmark, etc. will all work against our host controls for these types.

Data Binding
Data binding deserves special mention as this is really the most important reason we did the host control feature. Data binding is key to achieving data/view separation, allowing you to code against the data, and enabling some server side scenarios with Excel and Word documents that I'll discuss in a later blog.

Data binding allows a named range in excel, a bookmark in word--any of the host control types I've mentioned above--to participate in WinForms style data binding. This gives you a lot of power you didn't have before in Word and Excel with VSTO 1.0. You can now write code like this against a named range host control called “CustomerName”:

CustomerName.Databindings.Add(”Value2”, MyDataSet, “Customers.Name”, true)

where Value2 is the name of the property on the CustomerName host control you want to bind to, MyDataSet is your data set or data connector, and “Customer.Name“ is the name of the database table and column to bind to. The final “true” parameter is a departure from the Databindings.Add you may be familiar with--this is an additions to WinForms for VSTO 2.0 and is needed because our control supports formatting--I'll blog more about this later.

For ListObject, our only host control that supports complex data binding, you can do this:

Orders.SetDataBinding(MyDataSet, “Orders”)

ListObject acts like a DataGrid--but it is just the built-in Excel List you may be familiar with.

That's all for now on HostControls--I'll try to fill in some more detail in a later blog.

Comments

  • Anonymous
    April 12, 2004
    Thanks, very useful object model complement, complex databinding is always welcome-can't wait of entirely managed office with consistent programming model/features to rest of .NET/Longhorn framework;-)
    Easier=logical programming model is 75% of powerful=flexible application...
    By the way,when all these sweeties will be available?
  • Anonymous
    April 12, 2004
    Maybe some markup functionality can be useful too,something like:
    <Range id="MyRange" Onchange="Handler"/>
    for notepad lovers.
  • Anonymous
    April 12, 2004
    Will it support binding to any custom object or just to DataSets?
  • Anonymous
    April 13, 2004
    Great news.

    Does this mean that we will be able to host Word and Excel in a Windows Form seamlessly?
  • Anonymous
    April 13, 2004
    Duque -- Whidbey has support for hosting Office documents inside WinForms, but currently we do not support hosting VSTO code inside Office inside WinForms... that's just too much COM goo happening in one application ;-). It might work, but it might break, too.

    (And in Everettt you can host the WebBrowser control which then hosts the Office document... but it's a bit messy).
  • Anonymous
    April 14, 2004
    It will support binding to any object that you can currently databind a WinForms control to.

    For more information on data providers in WinForms see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbcon/html/vbconprovidersofdatatowindowsforms.asp

    Also there is some new stuff coming in Visual Studio 2005 that lets you pick various additional things like web services to bind to.