How to: Set a custom property in a word processing document
TOC
Collapse the table of content
Expand the table of content

How to: Set a custom property in a word processing document (Open XML SDK)

Office 2013 and later

This topic shows how to use the classes in the Open XML SDK 2.5 for Office to programmatically set a custom property in a word processing document. It contains an example SetCustomProperty method to illustrate this task.

Last modified: March 22, 2013

Applies to: Office 2013 | Open XML

In this article
How Custom Properties Are Stored
SetCustomProperty Method
Calling the SetCustomProperty Method
How the Code Works
Working with the Document
Sample Code

To use the sample code in this topic, you must install the Open XML SDK 2.5. You must explicitly reference the following assemblies in your project:

  • WindowsBase

  • DocumentFormat.OpenXml (installed by the Open XML SDK)

You must also use the following using directives or Imports statements to compile the code in this topic.

Imports System.IO
Imports DocumentFormat.OpenXml.CustomProperties
Imports DocumentFormat.OpenXml.Packaging
Imports DocumentFormat.OpenXml.VariantTypes

The sample code also includes an enumeration that defines the possible types of custom properties. The SetCustomProperty method requires that you supply one of these values when you call the method.

Public Enum PropertyTypes
    YesNo
    Text
    DateTime
    NumberInteger
    NumberDouble
End Enum

It is important to understand how custom properties are stored in a word processing document. You can use the Productivity Tool for Microsoft Office, shown in Figure 1, to discover how they are stored. This tool enables you to open a document and view its parts and the hierarchy of parts. Figure 1 shows a test document after you run the code in the Calling the SetCustomProperty Method section of this article. The tool displays in the right-hand panes both the XML for the part and the reflected C# code that you can use to generate the contents of the part.

Figure 1. Open XML SDK Productivity Tool for Microsoft Office

Open XML SDK 2.0 Productivity Tool


The relevant XML is also extracted and shown here for ease of reading.

<op:Properties xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes" xmlns:op="http://schemas.openxmlformats.org/officeDocument/2006/custom-properties">
  <op:property fmtid="{D5CDD505-2E9C-101B-9397-08002B2CF9AE}" pid="2" name="Manager">
    <vt:lpwstr>Mary</vt:lpwstr>
  </op:property>
  <op:property fmtid="{D5CDD505-2E9C-101B-9397-08002B2CF9AE}" pid="3" name="ReviewDate">
    <vt:filetime>2010-12-21T00:00:00Z</vt:filetime>
  </op:property>
</op:Properties>

If you examine the XML content, you will find the following:

  • Each property in the XML content consists of an XML element that includes the name and the value of the property.

  • For each property, the XML content includes an fmtid attribute, which is always set to the same string value: {D5CDD505-2E9C-101B-9397-08002B2CF9AE}.

  • Each property in the XML content includes a pid attribute, which must include an integer starting at 2 for the first property and incrementing for each successive property.

  • Each property tracks its type (in the figure, the vt:lpwstr and vt:filetime element names define the types for each property).

The sample method that is provided here includes the code that is required to create or modify a custom document property in a Microsoft Word 2010 or Microsoft Word 2013 document. You can find the complete code listing for the method in the Sample Code section.

You can use the SetCustomProperty method to set a custom property in a word processing document. The SetCustomProperty method accepts four parameters:

  • The name of the document to modify (string).

  • The name of the property to add or modify (string).

  • The value of the property (object).

  • The kind of property (one of the values in the PropertyTypes enumeration).

Public Function SetCustomProperty( _
    ByVal fileName As String,
    ByVal propertyName As String, _
    ByVal propertyValue As Object,
    ByVal propertyType As PropertyTypes) As String

The SetCustomProperty method enables you to set a custom property, and returns the current value of the property, if it exists. To call the sample method, pass the file name, property name, property value, and property type parameters. The following sample code shows an example.

Const fileName As String = "C:\Users\Public\Documents\SetCustomProperty.docx"

Console.WriteLine("Manager = " &
    SetCustomProperty(fileName, "Manager", "Peter", PropertyTypes.Text))

Console.WriteLine("Manager = " &
    SetCustomProperty(fileName, "Manager", "Mary", PropertyTypes.Text))

Console.WriteLine("ReviewDate = " &
    SetCustomProperty(fileName, "ReviewDate",
    #12/21/2010#, PropertyTypes.DateTime))

After running this code, use the following procedure to view the custom properties from Word.

  1. Open the SetCustomProperty.docx file in Word.

  2. On the File tab, click Info.

  3. Click Properties.

  4. Click Advanced Properties.

The custom properties will display in the dialog box that appears, as shown in Figure 2.

Figure 2. Custom Properties in the Advanced Properties dialog box

Advanced Properties dialog with custom properties

The SetCustomProperty method starts by setting up some internal variables. Next, it examines the information about the property, and creates a new CustomDocumentProperty based on the parameters that you have specified. The code also maintains a variable named propSet to indicate whether it successfully created the new property object. This code verifies the type of the property value, and then converts the input to the correct type, setting the appropriate property of the CustomDocumentProperty object.

Note Note

The CustomDocumentProperty type works much like a VBA Variant type. It maintains separate placeholders as properties for the various types of data it might contain.

Dim returnValue As String = Nothing

Dim newProp As New CustomDocumentProperty
Dim propSet As Boolean = False

' Calculate the correct type:
Select Case propertyType

    Case PropertyTypes.DateTime
        ' Be sure you were passed a real date, 
        ' and if so, format in the correct way. 
        ' The date/time value passed in should 
        ' represent a UTC date/time.
        If TypeOf (propertyValue) Is DateTime Then
            newProp.VTFileTime = _
                New VTFileTime(String.Format("{0:s}Z",
                    Convert.ToDateTime(propertyValue)))
            propSet = True
        End If

    Case PropertyTypes.NumberInteger
        If TypeOf (propertyValue) Is Integer Then
            newProp.VTInt32 = New VTInt32(propertyValue.ToString())
            propSet = True
        End If

    Case PropertyTypes.NumberDouble
        If TypeOf propertyValue Is Double Then
            newProp.VTFloat = New VTFloat(propertyValue.ToString())
            propSet = True
        End If

    Case PropertyTypes.Text
        newProp.VTLPWSTR = New VTLPWSTR(propertyValue.ToString())
        propSet = True

    Case PropertyTypes.YesNo
        If TypeOf propertyValue Is Boolean Then
            ' Must be lowercase.
            newProp.VTBool = _
              New VTBool(Convert.ToBoolean(propertyValue).ToString().ToLower())
            propSet = True
        End If
End Select

If Not propSet Then
    ' If the code was not able to convert the 
    ' property to a valid value, throw an exception.
    Throw New InvalidDataException("propertyValue")
End If

At this point, if the code has not thrown an exception, you can assume that the property is valid, and the code sets the FormatId and Name properties of the new custom property.

' Now that you have handled the parameters, start
' working on the document.
newProp.FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}"
newProp.Name = propertyName

Given the CustomDocumentProperty object, the code next interacts with the document that you supplied in the parameters to the SetCustomProperty procedure. The code starts by opening the document in read/write mode by using the Open method of the WordprocessingDocument class. The code attempts to retrieve a reference to the custom file properties part by using the CustomFilePropertiesPart property of the document.

Using document = WordprocessingDocument.Open(fileName, True)
    Dim customProps = document.CustomFilePropertiesPart
    ' Code removed here...
End Using

If the code cannot find a custom properties part, it creates a new part, and adds a new set of properties to the part.

If customProps Is Nothing Then
    ' No custom properties? Add the part, and the
    ' collection of properties now.
    customProps = document.AddCustomFilePropertiesPart
    customProps.Properties = New Properties
End If

Next, the code retrieves a reference to the Properties property of the custom properties part (that is, a reference to the properties themselves). If the code had to create a new custom properties part, you know that this reference is not null. However, for existing custom properties parts, it is possible, although highly unlikely, that the Properties property will be null. If so, the code cannot continue.

Dim props = customProps.Properties
If props IsNot Nothing Then
  ' Code removed here...
End If

If the property already exists, the code retrieves its current value, and then deletes the property. Why delete the property? If the new type for the property matches the existing type for the property, the code could set the value of the property to the new value. On the other hand, if the new type does not match, the code must create a new element, deleting the old one (it is the name of the element that defines its type—for more information, see Figure 1). It is simpler to always delete and then re-create the element. The code uses a simple LINQ query to find the first match for the property name.

Dim prop = props.
  Where(Function(p) CType(p, CustomDocumentProperty).
          Name.Value = propertyName).FirstOrDefault()
' Does the property exist? If so, get the return value, 
' and then delete the property.
If prop IsNot Nothing Then
    returnValue = prop.InnerText
    prop.Remove()
End If

Now, you will know for sure that the custom property part exists, a property that has the same name as the new property does not exist, and that there may be other existing custom properties. The code performs the following steps:

  1. Appends the new property as a child of the properties collection.

  2. Loops through all the existing properties, and sets the pid attribute to increasing values, starting at 2.

  3. Saves the part.

' Append the new property, and 
' fix up all the property ID values. 
' The PropertyId value must start at 2.
props.AppendChild(newProp)
Dim pid As Integer = 2
For Each item As CustomDocumentProperty In props
    item.PropertyId = pid
    pid += 1
Next
props.Save()

Finally, the code returns the stored original property value.

Return returnValue

The following is the complete SetCustomProperty code sample in C# and Visual Basic.

Public Enum PropertyTypes
    YesNo
    Text
    DateTime
    NumberInteger
    NumberDouble
End Enum

Public Function SetCustomProperty( _
    ByVal fileName As String,
    ByVal propertyName As String, _
    ByVal propertyValue As Object,
    ByVal propertyType As PropertyTypes) As String

    ' Given a document name, a property name/value, and the property type, 
    ' add a custom property to a document. The method returns the original 
    ' value, if it existed.

    Dim returnValue As String = Nothing

    Dim newProp As New CustomDocumentProperty
    Dim propSet As Boolean = False

    ' Calculate the correct type:
    Select Case propertyType

        Case PropertyTypes.DateTime
            ' Make sure you were passed a real date, 
            ' and if so, format in the correct way. 
            ' The date/time value passed in should 
            ' represent a UTC date/time.
            If TypeOf (propertyValue) Is DateTime Then
                newProp.VTFileTime = _
                    New VTFileTime(String.Format("{0:s}Z",
                        Convert.ToDateTime(propertyValue)))
                propSet = True
            End If

        Case PropertyTypes.NumberInteger
            If TypeOf (propertyValue) Is Integer Then
                newProp.VTInt32 = New VTInt32(propertyValue.ToString())
                propSet = True
            End If

        Case PropertyTypes.NumberDouble
            If TypeOf propertyValue Is Double Then
                newProp.VTFloat = New VTFloat(propertyValue.ToString())
                propSet = True
            End If

        Case PropertyTypes.Text
            newProp.VTLPWSTR = New VTLPWSTR(propertyValue.ToString())
            propSet = True

        Case PropertyTypes.YesNo
            If TypeOf propertyValue Is Boolean Then
                ' Must be lowercase.
                newProp.VTBool = _
                  New VTBool(Convert.ToBoolean(propertyValue).ToString().ToLower())
                propSet = True
            End If
    End Select

    If Not propSet Then
        ' If the code was not able to convert the 
        ' property to a valid value, throw an exception.
        Throw New InvalidDataException("propertyValue")
    End If

    ' Now that you have handled the parameters, start
    ' working on the document.
    newProp.FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}"
    newProp.Name = propertyName

    Using document = WordprocessingDocument.Open(fileName, True)
        Dim customProps = document.CustomFilePropertiesPart
        If customProps Is Nothing Then
            ' No custom properties? Add the part, and the
            ' collection of properties now.
            customProps = document.AddCustomFilePropertiesPart
            customProps.Properties = New Properties
        End If

        Dim props = customProps.Properties
        If props IsNot Nothing Then
            ' This will trigger an exception is the property's Name property 
            ' is null, but if that happens, the property is damaged, and 
            ' probably should raise an exception.
            Dim prop = props.
              Where(Function(p) CType(p, CustomDocumentProperty).
                      Name.Value = propertyName).FirstOrDefault()
            ' Does the property exist? If so, get the return value, 
            ' and then delete the property.
            If prop IsNot Nothing Then
                returnValue = prop.InnerText
                prop.Remove()
            End If

            ' Append the new property, and 
            ' fix up all the property ID values. 
            ' The PropertyId value must start at 2.
            props.AppendChild(newProp)
            Dim pid As Integer = 2
            For Each item As CustomDocumentProperty In props
                item.PropertyId = pid
                pid += 1
            Next
            props.Save()
        End If
    End Using

    Return returnValue

End Function

Contribute to this article

Want to edit or suggest changes to this content? You can edit and submit changes to this article using GitHub.

Show:
© 2016 Microsoft