Working with Document Properties

The DocumentProperties collection and DocumentProperty object are found 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 are typically brought into your code in an Office namespace alias as shown here:

using 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

private void ThisWorkbook_Startup(object sender, EventArgs e)
{
  Office.DocumentProperties customProps = this.
    CustomDocumentProperties as Office.DocumentProperties;

  Office.DocumentProperties builtinProps = this.
    BuiltinDocumentProperties as Office.DocumentProperties;

  foreach (Office.DocumentProperty builtinProp in builtinProps)
  {
    MessageBox.Show(String.Format(
      "{0}  {1}", builtinProp.Name, builtinProp.Value));
  }

  foreach (Office.DocumentProperty customProp in customProps)
  {
    MessageBox.Show(String.Format(
      "{0}  {1}", customProp.Name, customProp.Value));
  }
}

Accessing a DocumentProperty in the DocumentProperties Collection

To access a DocumentProperty in a DocumentProperties collection, you use the C# indexing syntax docProperty[object], which returns a DocumentProperty object. The indexer takes an Index parameter of type object. You can pass an int 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 what the type is of Value by using the Type property that 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

private void ThisWorkbook_Startup(object sender, EventArgs e)
{
  Office.DocumentProperties builtinProps = this.
    BuiltinDocumentProperties as Office.DocumentProperties;

  Office.DocumentProperty authorProp = builtinProps["Author"];

  MessageBox.Show(String.Format(
    "Property {0} is {1}", authorProp.Name, authorProp.Value));

  Office.DocumentProperty thirdProp = builtinProps[3];

  MessageBox.Show(String.Format(
    "Property {0} is {1}", thirdProp.Name, thirdProp.Value));
}

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	bool	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 with 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

private void ThisWorkbook_Startup(object sender, EventArgs e)
{
  Office.DocumentProperties props = this.
    CustomDocumentProperties as Office.DocumentProperties;

  Office.DocumentProperty prop = props.Add("My Property",
    false, Office.MsoDocProperties.msoPropertyTypeString,
    "My Value", missing);

  MessageBox.Show(String.Format(
    "Property {0} has value {1}.", prop.Name, prop.Value));
}