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.
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 = trueDetails.ShowTotals = trueSalesResults.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:
Data BindingData 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:
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.