How to: Read from and Write to Document Properties

Applies to

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type Application-level projects Document-level projects Microsoft Office version Excel 2007 and Excel 2003 PowerPoint 2007 and PowerPoint 2003 Project 2007 and Project 2003 Word 2007 and Word 2003 For more information, see Features Available by Application and Project Type.

You can store document properties along with a document in the Microsoft Office applications listed above. These applications provide a number of built-in properties, such as author, title, and subject. This topic shows how to set document properties in Microsoft Office Excel and Microsoft Office Word.

For a related video demonstration, see How Do I: Access and Manipulate Custom Document Properties in Microsoft Word?.

Setting Document Properties in Excel

To work with built-in properties in Excel, use the following properties:

• In a document-level project, use the BuiltinDocumentProperties property of the ThisWorkbook class.

• In an application-level project, use the BuiltinDocumentProperties property of a Workbook object.

These properties return a DocumentProperties object, which is a collection of DocumentProperty objects. You can use the Item property of the collection to retrieve a particular property, either by name or by index within the collection.

The following code example shows how to change the built-in Revision Number property in a document-level project.

To change the Revision Number property in Excel

1. Assign the built-in document properties to a variable.

   Dim properties As Microsoft.Office.Core.DocumentProperties
   
   properties = DirectCast(Globals.ThisWorkbook.BuiltinDocumentProperties, _
       Microsoft.Office.Core.DocumentProperties)
   
   Dim prop As Microsoft.Office.Core.DocumentProperty
   prop = properties.Item("Revision Number")
   

   Microsoft.Office.Core.DocumentProperties properties;
   
   properties = (Microsoft.Office.Core.DocumentProperties)
       Globals.ThisWorkbook.BuiltinDocumentProperties; 
   
   Microsoft.Office.Core.DocumentProperty prop;
   prop = properties["Revision Number"]; 
   

2. Increment the Revision Number property by one.

   If prop.Value Is Nothing Then
       prop.Value = 1
   Else 
       Dim revision As Integer 
       If Integer.TryParse(prop.Value.ToString(), revision) Then
           prop.Value = revision + 1
           MessageBox.Show("Revision Number = " & revision)
       Else
           MessageBox.Show("Revision Number = invalid value")
       End If 
   End If
   

   if (prop.Value == null)
   {
       prop.Value = 1;
   }
   else
   {
       int revision;
       if (int.TryParse((string)prop.Value, out revision))
       {
           prop.Value = revision + 1;
           MessageBox.Show("Revision Number = " + revision);
       }
       else
       {
           MessageBox.Show("Revision Number = invalid value");
       }
   }
   

Setting Document Properties in Word

To work with built-in properties in Word, use the following properties:

• In a document-level project, use the BuiltInDocumentProperties property of the ThisDocument class.

• In an application-level project, use the BuiltInDocumentProperties property of a Document object.

These properties return a DocumentProperties object, which is a collection of DocumentProperty objects. You can use the Item property of the collection to retrieve a particular property, either by name or by index within the collection.

The following code example shows how to change the built-in Subject property in a document-level project.

To change the Subject property

1. Assign the built-in document properties to a variable.

   Dim properties As Microsoft.Office.Core.DocumentProperties
   
   properties = DirectCast(Globals.ThisDocument.BuiltInDocumentProperties, _
       Microsoft.Office.Core.DocumentProperties)
   

   Microsoft.Office.Core.DocumentProperties properties;
   
   properties = (Microsoft.Office.Core.DocumentProperties)
       Globals.ThisDocument.BuiltInDocumentProperties; 
   

2. Change the Subject property to "Whitepaper".

   ' Set the Subject property.
   properties.Item("Subject").Value = "Whitepaper"
   

   // Set the Subject property. 
   properties["Subject"].Value = "Whitepaper"; 
   

Robust Programming

Although you are working with Word and Excel and their objects, Microsoft Office supplies the list of available built-in document properties. Attempting to access an undefined property raises an exception.

See Also

Tasks

How to: Create and Modify Custom Document Properties

Concepts

Programming Application-Level Add-Ins

Programming Document-Level Customizations