Working with Document Properties

The DocumentProperties collection and DocumentProperty object are located in the Microsoft Office 11.0 Object Library (office.dll), which contains objects shared by all the Office applications. These objects are in the Microsoft.Office.Core namespace and typically are brought into your code in an Office namespace alias as shown here:

Imports Office = Microsoft.Office.Core

Iterating over the DocumentProperties Collection

Listing 5.15 shows an example of iterating over the DocumentProperties collection returned by Workbook.CustomDocumentProperties and Workbook.BuiltInDocumentProperties.

Listing 5.15. A VSTO Customization That Iterates over DocumentProperties Collection

Public Class ThisWorkbook   Private Sub ThisWorkbook_Startup(ByVal sender As Object, _     ByVal e As System.EventArgs) Handles Me.Startup     Dim builtinProps As Office.DocumentProperties     builtinProps = Me.BuiltinDocumentProperties     Dim customProps As Office.DocumentProperties     customProps = Me.CustomDocumentProperties     Dim builtinProp As Office.DocumentProperty     For Each builtinProp In builtinProps       Try         MsgBox(String.Format("{0}  {1}", _           builtinProp.Name, builtinProp.Value))       Catch         MsgBox(String.Format("{0} has not been set.", _           builtinProp.Name))       End Try     Next     Dim customProp As Office.DocumentProperty     For Each customProp In customProps       Try         MsgBox(String.Format("{0}  {1}", _           customProp.Name, customProp.Value))       Catch         MsgBox(String.Format("{0} has not been set.", _           customProp.Name))       End Try     Next   End Sub End Class 

Accessing a DocumentProperty in the DocumentProperties Collection

To access a DocumentProperty in a DocumentProperties collection, you use the Visual Basic indexing syntax docProperties(Object), which returns a DocumentProperty object. This syntax is actually calling the default property Item on the DocumentProperties collection. The indexer takes an Index parameter of type Object. You can pass an Integer representing the 1-based index of the DocumentProperty in the collection you want to access. Alternatively, you can pass a String representing the name of the DocumentProperty you want to access. As with other collections, the Count property returns how many DocumentProperty objects are in the collection.

A DocumentProperty object has a Name property that returns a String containing the name of the property. It also has a Value property of type Object that returns the value of the property. You can check the type Value by using the Type property, which returns a member of the MsoDocProperties enumeration: msoPropertyTypeBoolean, msoPropertyTypeDate, msoPropertyTypeFloat, msoPropertyTypeNumber, or msoPropertyTypeString.

Listing 5.16 shows how a DocumentProperty is accessed.

Listing 5.16. A VSTO Customization That Accesses a DocumentProperty Using an Indexer

Public Class ThisWorkbook   Private Sub ThisWorkbook_Startup(ByVal sender As Object, _     ByVal e As System.EventArgs) Handles Me.Startup     Dim builtinProps As Office.DocumentProperties     builtinProps = Me.BuiltinDocumentProperties     Dim authorProp As Office.DocumentProperty     authorProp = builtinProps("Author")     MsgBox(String.Format("Property {0} is {1}", _       authorProp.Name, authorProp.Value))     Dim thirdProp As Office.DocumentProperty = builtinProps(3)     MsgBox(String.Format("Property {0} is {1}", _       thirdProp.Name, thirdProp.Value))   End Sub End Class 

Adding a DocumentProperty

You can add a custom DocumentProperty using the Add method. The Add method takes the parameters shown in Table 5.10.

Table 5.10. Parameters for the DocumentProperties Collection's Add Method

Parameter Name	Type	What It Does
Name	String	Sets the name of the new DocumentProperty.
LinkToContent	Boolean	Sets whether the property is linked to the contents of the container document.
Type	optional Object	Sets the data type of the property. Can be one of the following MsoDocProperties enumerated values: msoPropertyTypeBoolean, msoPropertyTypeDate, msoPropertyTypeFloat, msoPropertyTypeNumber, or msoPropertyTypeString.
Value	optional Object	Sets the value of the property if LinkToContent is False.
LinkSource	optional Object	Sets the source of the linked property if LinkToContent is TRue.

Listing 5.17 shows an example of adding a custom DocumentProperty of type msoPropertyTypeString. Note that Excel will let you set the value to a long string, but it will truncate it to 255 characters. Fortunately, VSTO provides developers a way to store larger amounts of data in a document through a feature called cached data. For more information on the cached-data feature of VSTO, see Chapter 18, "Server Data Scenarios."

Listing 5.17. A VSTO Customization That Adds a Custom DocumentProperty

Public Class ThisWorkbook   Private Sub ThisWorkbook_Startup(ByVal sender As Object, _     ByVal e As System.EventArgs) Handles Me.Startup     Dim props As Office.DocumentProperties     props = Me.CustomDocumentProperties     Dim prop As Office.DocumentProperty     prop = props.Add("My Property", False, _       Office.MsoDocProperties.msoPropertyTypeString, "My Value")     MsgBox(String.Format("Property {0} has value {1}.", _       prop.Name, prop.Value))   End Sub End Class