Visual Studio Tools for Office: Using Visual Basic 2005 with Excel, Word, Outlook, and InfoPath

2017-07-07 02:10:07

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

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