How to: Read from and write to document properties

Article
02/02/2017

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

You can store document properties along with a document. Office 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.

Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for the following applications: Excel; PowerPoint; Project; Word. For more information, see Features available by Office application and project type.

Set 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 a VSTO Add-in 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

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"];

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");
    }
}

Set 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 a VSTO Add-in 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

Assign the built-in document properties to a variable.

Microsoft.Office.Core.DocumentProperties properties;

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

Dim properties As Microsoft.Office.Core.DocumentProperties

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

Change the Subject property to "Whitepaper".

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

' Set the Subject property.
properties.Item("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.