How to: Read from and Write to Document Properties

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?.

Applies to: The information in this topic applies to document-level projects and application-level projects for the following applications: Excel 2007 and Excel 2010; PowerPoint 2007 and PowerPoint 2010; Project 2007 and Project 2010; Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.

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 Microsoft.Office.Interop.Excel.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 Microsoft.Office.Interop.Word.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

The examples assume that you have written the code in the ThisWorkbook class in a document-level project for Excel, and the ThisDocument class in a document-level project for Word.

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

Other Resources

Programming Application-Level Add-Ins

Programming Document-Level Customizations