Tech Blog: Geek factor 9/10

I was working on a Visual Studio Tools for Office VSTO solution with Beta 2 of Visual Studio 2005 and I needed a way to hold some configuration data for the document I was working with.  I heard that you can save the data within the document itself into something called a data island and I thought this would be ideal to save my configuration data.

I won’t go into the technicalities of the solution I was working on only to say that I needed a way to store a DataTable within a Word document that could be accessed at Runtime by the VSTO libraries to then act as the configuration options of my solution.

So there is two elements to this.

1. Store a datatable to a word document.
2. Access the data at runtime from my VSTO document class.

I’m afraid it’s not an elegant solution and there may be issues with the way that I’m doing it but it appears to work for me and hopefully if you are looking to do this it gives you a head start.  Thanks to some of the guys on the VSTO team at Microsoft for providing me with some information. 

To access a document and insert a DataTable you will need a reference to Microsoft.VisualStudio.Tools.Applications.Runtime.

All code was written is C#.  I’m a glutton for punishment.

//get a reference to the document in the form of a ServerDocument class

//pass the parameter false to create document without starting Word.

ServerDocument MyDoc = new ServerDocument(@"C:\test\MyWordDoc.dot", false);

//the top level of the cached data hierarchy is the Host item

// this is indexed by using the class name of the VSTO solution

CachedDataHostItem hostItem =

    MyDoc.CachedData.HostItems["MyWordDoc.ThisDocument"];

//if no reference then add the item

if (hostItem == null)

    hostItem = MyDoc.CachedData.HostItems.Add("MyWordDoc.ThisDocument");

//Now get the cached data from the Host item

CachedDataItem cache = hostItem.CachedData["_cachedData"];

//again if this does not exist create it as a dataset with an indexer of _cachedData

if (cache == null)

    cache = hostItem.CachedData.Add("_cachedData", "DataSet");

// create a new dataset to insert into the doc containing our new data table.  I’ve kept this

// sample simple but in reality you would probably build a proper data table

DataSet ds = new DataSet("_cachedData");

DataTable tbl = new DataTable("NewTable");

ds.Tables.Add(tbl);

cache.SerializeDataInstance(ds);

//save and close the ServerDocument

MyDoc.Save();

MyDoc.Close();

That’s it our VSTO document now has cached data within it that can be accessed by using the same object collections of CachedDataHostItem containing CachedDataItems.

Now what I needed to do was to access the cached data within a document from within theVSTO projects ThisDocument class itself.

By declaring a public DataSet within the ThisDocument class and giving it the cached attribute when you run the VSTO solutution the VSTO runtime will look for this dataset and populate it if the document contains cached data.  Here is the declaration to enable this.

public partial class ThisDocument

{

        //data island within the document 
        [Microsoft.VisualStudio.Tools.Applications.Runtime.Cached()]
        public DataSet _cachedData;

If the document contains cached data the _cachedData variable will be populated.

It is also possible to cache data into a Word document that isn’t enabled for VSTO in other words it has no embedded application manifest.  When you create the ServerDocument object pass the second parameter true which will create the document object using Word, known as client side, as opposed to server side.  To do this you will need to have Word installed on the machine.

ServerDocument MyDoc = new ServerDocument(@"C:\test\MyWordDoc.dot", true);

One last point is that caching is allowed on any serialisable type so that opens up all sorts of options.

I hope this has given you enough information to get to grips with this technology if it’s something you want to do.  It's certainly a useful feature and one I am using myself.