How to: Create and modify custom document properties

Applies to: Visual Studio Visual Studio for Mac

The Microsoft Office applications listed above provide built-in properties that are stored with documents. In addition, you can create and modify custom document properties if there is additional information you want to store with the document.

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.

Use the CustomDocumentProperties property of a document to work with custom properties. For example, in a document-level project for Microsoft Office Excel, use the CustomDocumentProperties property of the ThisWorkbook class. In a VSTO Add-in project for Excel, use the CustomDocumentProperties 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 example demonstrates how to add a custom property in a document-level customization for Excel and assign it a value.

Example

Sub TestProperties()
    Dim properties As Microsoft.Office.Core.DocumentProperties
    properties = CType(Me.CustomDocumentProperties, Office.DocumentProperties)

    If ReadDocumentProperty("Project Name") <> Nothing Then
        properties("Project Name").Delete()
    End If

    properties.Add("Project Name", False, _
        Microsoft.Office.Core.MsoDocProperties.msoPropertyTypeString, _
        "White Papers")
End Sub

Private Function ReadDocumentProperty(ByVal propertyName As String) As String
    Dim properties As Office.DocumentProperties
    properties = CType(Me.CustomDocumentProperties, Office.DocumentProperties)

    Dim prop As Office.DocumentProperty

    For Each prop In properties
        If prop.Name = propertyName Then
            Return prop.Value.ToString()
        End If
    Next

    Return Nothing
End Function

void TestProperties()
{
    Microsoft.Office.Core.DocumentProperties properties;
    properties = (Office.DocumentProperties)this.CustomDocumentProperties;

    if (ReadDocumentProperty("Project Name") != null)
    {
        properties["Project Name"].Delete();
    }

    properties.Add("Project Name", false,
        Microsoft.Office.Core.MsoDocProperties.msoPropertyTypeString,
        "White Papers");
}

private string ReadDocumentProperty(string propertyName)
{
    Office.DocumentProperties properties;
    properties = (Office.DocumentProperties)this.CustomDocumentProperties;

    foreach (Office.DocumentProperty prop in properties)
    {
        if (prop.Name == propertyName)
        {
            return prop.Value.ToString();
        }
    }
    return null;
}

Robust programming

Attempting to access the Value property for undefined properties raises an exception.

See also

• Program VSTO Add-ins
• Program document-level customizations
• How to: Read from and write to document properties