Reading and Writing Custom Document Properties in Microsoft Office Word 2003 with Microsoft Visual Basic .NET

Summary: Document properties in Microsoft Office Word 2003 provide a way to describe a document. Custom properties extend this ability by allowing you to define your own properties. This article illustrates how to automate Microsoft Office Word 2003 with Microsoft Visual Basic .NET to retrieve and to manipulate document properties. (6 printed pages)

Frank Rice, Microsoft Corporation

January 2004

Applies to: Microsoft Office Word 2003


  • Overview

  • Adding Custom Properties by Using the Property Dialog Box

  • Create a Custom Property Programmatically

  • Conclusion


Document properties in Microsoft Office Word 2003 contain basic information about a document such as the file name, author, creation date, date last saved, number of words, and so forth. The purpose of document properties is to provide a common way to describe any document. Custom properties extend the role of standard properties by providing you with a way to add and populate properties with additional information about the document. You can add custom properties through the Properties dialog box or programmatically using the Add method of the CustomDocumentProperties collection. This article demonstrates both methods.


Although the sample in this article is specifically written to automate Word, you can apply the same concepts to Microsoft Office Excel 2003 and Microsoft Office PowerPoint 2003.

Adding Custom Properties by Using the Property Dialog Box

Besides the text in your document, Word also maintains quite a bit of statistical and other information about your document with standard properties. You can view a portion of this information by choosing the Properties option from the File menu. Word then displays the Properties dialog box for your document, where you can use the different tabs to view the information maintained there.

In addition to the standard properties maintained by Word, you can create your own custom document properties. To create a custom document property, follow these steps:

  1. On the File menu, click Properties. Word displays the Properties dialog box for your document.

  2. Select the Custom tab.

    Figure 1. The Custom tab of the Properties dialog box

    The Custom tab of the Properties dialog box

  3. In the Name box, type the name you want to use for your new document property.

  4. Using the Type drop-down list, specify the type that best describes what you want to store in this document property.

  5. In the Value box, type the value you want to assign to the property.

  6. Click Add. Your new property appears at the bottom of the dialog box, in the Properties list.

  7. Click OK to dismiss the Properties dialog box.

Create a Custom Property Programmatically

In addition to adding and populating custom properties from the Properties dialog box, you can also do this programmatically by using the Add method of the CustomDocumentProperties collection. You can also use this same collection to set or retrieve the property values. You can access the individual by using an index value in the collection or through the name of the property. The name is the preferred method as the index changes as you add and remove properties. To add a custom property from Microsoft Visual Basic .NET, you must use automation to start Word and access the collections, properties, and methods of Word. To do so, use the following steps:

To create an automation client for Word in Visual Basic .NET:

  1. Start Visual Studio .NET.

  2. On the File menu, click New, and then click Project. Select Windows Application from the Visual Basic Project types. Form1 is created by default.

  3. Add a reference to Microsoft Word Object 11.0 Library. To do this, follow these steps:

    • On the Project menu, click Add Reference.

    • On the COM tab, locate the Microsoft Word Object 11.0 Library, and then click Select.


      The Microsoft Office System includes Primary Interop Assemblies (PIAs). Microsoft Office XP does not include PIAs, but you can download them. For more information about Office XP PIAs, see the Microsoft Knowledge Base article 328912-INFO: Microsoft Office XP PIAs Are Available for Download.

    • Click OK in the Add References dialog box to accept your selections. If you are prompted to generate wrappers for the libraries that you selected, click Yes.

  4. On the View menu, click Toolbox to display the Toolbox, and add a button to Form1.

  5. Double-click Button1. The code window for the form appears.

  6. In the code window, add the following lines to the top of the code window:

       Imports Word = Microsoft.Office.Interop.Word
       Imports Office = Microsoft.Office.Core
  7. Next, replace the following code

    Private Sub Button1_Click(ByVal sender As System.Object, _
                   ByVal e As System.EventArgs) _
                   Handles Button1.Click
    End Sub


    Private Sub Button1_Click(ByVal sender As System.Object, _
                   ByVal e As System.EventArgs) _
                   Handles Button1.Click
       Dim oWord As Word.Application
       Dim oDoc As Word.Document
       Dim oBuiltInProps As Object
       Dim oCustomProps As Object
       Dim oProp As Object
       Dim strValue As String
       'Create an instance of Word and make it visible.
       oWord = CreateObject("Word.Application")
       oWord.Visible = True
       'Create a new document.
       oDoc = oWord.Documents.Add()
       'Get the Built-in Document Properties collection.
       oBuiltInProps = oDoc.BuiltInDocumentProperties
       'Get the value of the Author property and display it.
       strValue = oBuiltInProps.Item("Author").Value
       MsgBox("The author of this document is " & strValue)
       'Set the value of the Subject property.
       'Note that the maximum length of the property is 
       'is 256 characters.
       oBuiltInProps.Item("Subject").Value = _
          "Status Report for Human Resources"
       'Get the Custom Document Properties collection.
       oCustomProps = oDoc.CustomDocumentProperties
       'Add a property named Status Report
       'and give it a value of 4<SUP>th</SUP> Qtr.
       oCustomProps.Add("Status Report ", False, _
           Office.MsoDocProperties.msoPropertyTypeString, "4<SUP>th</SUP> Qtr")
       'Display a message box to give the user a chance to verify the
       MsgBox("Select Properties from the File menu " _
          & "to view the changes." & Chr(10) _
          & "Select the Summary tab to view " _
          & "the Subject and the Custom tab to view the Custom " _
          & "properties.", MsgBoxStyle.Information, _
          "Check File Properties")
       'Clean up, leaving Word running.
       oCustomProps = Nothing
       oBuiltInProps = Nothing
       oDoc = Nothing
       oWord = Nothing
    End Sub 
  8. Press F5 to run the application.

  9. Click Button1 to start Microsoft Word.

  10. When prompted, on the File menu, click Properties

This code demonstrates reading and writing both the built-in document properties and the custom document properties. When run, this code displays the value of the built-in Author property, changes the Subject property value to "Status Report for Human Resources," and creates a custom document property named "Status Report."


In this article, you learned the difference between standard Word properties and custom properties. You also created custom properties from the Property dialog box and programmatically using the CustomDocumentProperties collection. Custom properties give you the means to store information easily that you deem important.