Share via


How to: Read from and write to document properties

Applies to: yesVisual Studio noVisual 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

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

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

  1. 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)
    
  2. 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.

See also