{"id":50743,"date":"2010-04-06T00:01:00","date_gmt":"2010-04-06T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2010\/04\/06\/hey-scripting-guy-how-can-i-add-custom-properties-to-a-microsoft-word-document\/"},"modified":"2010-04-06T00:01:00","modified_gmt":"2010-04-06T00:01:00","slug":"hey-scripting-guy-how-can-i-add-custom-properties-to-a-microsoft-word-document","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/hey-scripting-guy-how-can-i-add-custom-properties-to-a-microsoft-word-document\/","title":{"rendered":"Hey, Scripting Guy! How Can I Add Custom Properties to a Microsoft Word Document?"},"content":{"rendered":"

\"Bookmark<\/a><\/p>\n

 \n\"Hey,<\/p>\n

Hey, Scripting Guy! A few months ago, you wrote a really cool Hey, Scripting Guy! post, How Can I Retrieve the Custom Properties of a Microsoft Word Document<\/font><\/a>. The post illustrated how to use Windows PowerShell to read the custom properties from Microsoft Word documents. You, however, did not show how to modify the value of custom properties. I am wondering if you would care to tackle that task now?<\/p>\n

— JB<\/p>\n

\n

 <\/p>\n<\/p>\n

\"Hey,Hello JB, <\/p>\n

Microsoft Scripting Guy Ed Wilson here. I am sipping a cup of English Breakfast tea with a little lemon grass and a stick of cinnamon in it. I was able to score some Tim Tams from my friend Brent in Sydney recently while he was in the United States for the Microsoft TechReady conference in Seattle, Washington, so things are progressing nicely this morning. I have Cream<\/font><\/a> cranked up so loud on my Zune HD<\/font><\/a> that I can feel the energetic Jack Bruce<\/font><\/a> bass licks deep inside my bones, and therefore I am sipping, munching, and grooving as I review the e-mail sent to the scripter@microsoft.com<\/font><\/a> address. I have no idea where the Scripting Wife is right now. She evacuated the upstairs about the time that Sunshine of Your Love<\/font><\/a> came on, and she was long gone by the time Badge<\/font><\/a> was playing. She took her laptop with her and muttered something about me being “impossible at times”—as if she weren’t alive in the 1970s or something. <\/p>\n

Anyway, as I was reviewing the e-mail inbox, I ran across Jit’s message. I knew it was Jit because I recognized his e-mail address. I first met Jit several years ago in Brisbane, Australia<\/font><\/a>, when I went there to teach a VBScript class that was based upon one of my VBScript books<\/font><\/a>. He was the Microsoft guy that I was to train to deliver my class and I got to work with him for two weeks—one week in Brisbane and one in Sydney. We have since become great friends. Thinking of Jit reminded me of some of the pictures I took during that trip, such as the following one that was taken in downtown Brisbane. <\/p>\n

\"Photo<\/p>\n

\n

 <\/p>\n<\/p>\n

JB, I decided to write the Set-WordCustomProperties.ps1 script for you to allow you to set custom properties on a Microsoft Word document. You should refer to the Hey, Scripting Guy! post<\/font><\/a> you mentioned in your e-mail message for information about working with custom properties in Microsoft Word, as well as for additional information about working with the InvokeMember<\/b> method. The complete Set-WordCustomProperties.ps1 script is seen here. <\/p>\n

Set-WordCustomProperties.ps1<\/p>\n

<\/strong><\/p>\n

$path = “C:fsoTest.docx”
$application = New-Object -ComObject word.application
$application.Visible = $false
$document = $application.documents.open($path)
$binding = “System.Reflection.BindingFlags” -as [type]<\/p>\n

$customProperties = $document.CustomDocumentProperties
$typeCustomProperties = $customProperties.GetType()<\/p>\n

$CustomProperty = “Client”
$Value = “My_WayCool_Client”
[array]$arrayArgs = $CustomProperty,$false, 4, $Value<\/p>\n

Try
 <\/span>{
  <\/span>$typeCustomProperties.InvokeMember(`
    <\/span>“add”, $binding::InvokeMethod,$null,$customProperties,$arrayArgs) |
    <\/span>out-null
 <\/span>}
Catch [system.exception]
 <\/span>{
  <\/span>$propertyObject = $typeCustomProperties.InvokeMember(`
    <\/span>“Item”, $binding::GetProperty,$null,$customProperties,$CustomProperty)
  <\/span>$typeCustomProperties.InvokeMember(`
    <\/span>“Delete”, $binding::InvokeMethod,$null,$propertyObject,$null)
  <\/span>$typeCustomProperties.InvokeMember(`
    <\/span>“add”, $binding::InvokeMethod,$null,$customProperties,$arrayArgs) |
    <\/span>Out-Null
 <\/span>}
 <\/span>
$document.Saved = $false
$document.save()
$application.quit()
$application = $null
[gc]::collect()
[gc]::WaitForPendingFinalizers()<\/p>\n

<\/font><\/font><\/span><\/p>\n

JB, the first thing to do is to assign the path to the document. In reality, this could be a Get-ChildItem<\/b> cmdlet that filters all of the document files, in the same manner that was used in yesterday’s Excel article<\/span><\/a>. The reason I left that part out of the script is that the script was already rather complicated, and I did not want to clutter it up anymore than it already was:<\/p>\n

$path = “C:fsoTest.docx”<\/p>\n

<\/font><\/span><\/p>\n

When working with Microsoft Word, it is generally a requirement to create an instance of the Word.Application<\/b> COM object. When the Word.Application<\/b> object is stored in the $application<\/b> variable, the visible<\/b> property is set to false<\/b> to keep the Word document from displaying on the screen. This is shown here: <\/p>\n

$application = New-Object -ComObject word.application
$application.Visible = $false<\/p>\n

<\/font><\/span><\/p>\n

It is time to open the Microsoft Word document, and to store the returned Document<\/b> object in the $document<\/b> variable. This is seen here:<\/p>\n

$document = $application.documents.open($path)<\/p>\n

<\/font><\/span><\/p>\n

Because of the way that the COM interop works, the BindingFlags<\/b> class from the System.Reflection<\/b> namespace needs to be created as a type. This is stored in the $binding<\/b> variable as shown here. The BindingFlags<\/b> class will be used several times in the Set-WordCustomProperties.ps1 script:<\/p>\n

$binding = “System.Reflection.BindingFlags” -as [type]<\/p>\n

<\/font><\/span><\/p>\n

Obtain the CustomDocumentProperties<\/b> collection by calling the CustomDocumentProperties<\/b> property. The object is stored in the $customProperties<\/b> variable:<\/p>\n

$customProperties = $document.CustomDocumentProperties<\/p>\n

<\/font><\/span><\/p>\n

It is time to retrieve the CustomDocumentProperties<\/b> type by using the GetType<\/b> method. The CustomDocumentProperties<\/b> type is stored in the $typeCustomProperties<\/b> variable. This type will be used later on in the script:<\/p>\n

$typeCustomProperties = $customProperties.GetType()<\/p>\n

<\/font><\/span><\/p>\n

Next, an array with the custom property name and the value of the custom property is created. The $arrayArgs<\/b> variable stores this information. When creating a custom document property, the add method<\/font><\/a> requires four or five different values. The first is the name of the property, and the second specifies whether the property is linked to the contents of the document. If this is set to $true<\/b>, the LinkSource<\/b> value must also be specified. If instead it is $false<\/b>, you must specify the value for the property. The third position is a MsoDocProperties<\/font><\/a> constant value. Rather than creating the actual enumeration, I used the direct value of 4, which is a msoPropertyTypeString<\/b> value. The following table lists the MsoDocProperties<\/b> enumerations and the enumeration values.<\/p>\n

<\/p>\n\n\n\n\n\n\n\n\n
\n

Name<\/p>\n

<\/b><\/p>\n<\/td>\n

\n

Value <\/p>\n

<\/b><\/p>\n<\/td>\n

\n

Description<\/p>\n

<\/b><\/p>\n<\/td>\n<\/tr>\n

\n

msoPropertyTypeBoolean<\/p>\n<\/td>\n

\n

2<\/p>\n<\/td>\n

\n

Boolean value<\/p>\n<\/td>\n<\/tr>\n

\n

msoPropertyTypeDate<\/p>\n<\/td>\n

\n

3<\/p>\n<\/td>\n

\n

Date value<\/p>\n<\/td>\n<\/tr>\n

\n

msoPropertyTypeFloat<\/p>\n<\/td>\n

\n

5<\/p>\n<\/td>\n

\n

Floating point value<\/p>\n<\/td>\n<\/tr>\n

\n

msoPropertyTypeNumber<\/p>\n<\/td>\n

\n

1<\/p>\n<\/td>\n

\n

Integer value<\/p>\n<\/td>\n<\/tr>\n

\n

msoPropertyTypeString<\/p>\n<\/td>\n

\n

4<\/p>\n<\/td>\n

\n

String value<\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

The LinkSource<\/b>, in the fifth position, would point to the source of the linked property if the LinkToContent<\/b> position was equal to $true<\/b>. This section of the script is shown here:<\/p>\n

$CustomProperty = “Client”
$Value = “My_WayCool_Client”
[array]$arrayArgs = $CustomProperty,$false, 4, $Value<\/p>\n

<\/font><\/span><\/p>\n

If the custom document property already exists and an attempt is made to write to the property, an error will be generated. To prevent the error from occurring, use the Try\/Catch<\/b> construction. In the Try<\/b> block, the InvokeMember<\/b> method from the CustomDocumentProperties<\/b> type is used to add the property to the CustomDocumentProperties<\/b> collection. If the custom property does not exist, no error is generated, and the property will be added to CustomDocumentProperties<\/b> collection. Following the Add<\/b> method, the InvokeMethod<\/b> static property is used from the Binding Flags<\/b> type. The CustomDocumentProperties<\/b> object is passed, as well as the array containing the information required by the add<\/b> method. This is rather complicated and is a requirement because of the way the COM interop model works. The returned system.object<\/b> is piped to the Out-Null<\/b> cmdlet to keep from cluttering up the Windows PowerShell console. The Try<\/b> section of the script is shown here. The line continuation character (`<\/b>) is used to allow the code block to display properly on our Web page. Normally I would type the InvokeMember<\/b> command on a single line. <\/p>\n

Try
 <\/span>{
  <\/span>$typeCustomProperties.InvokeMember(`
    <\/span>“add”, $binding::InvokeMethod,$null,$customProperties,$arrayArgs) |
    <\/span>out-null
 <\/span>}<\/p>\n

<\/font><\/span><\/p>\n

If the custom property already exists and an error is generated, control of the script moves to the Catch<\/b> block. The first thing that must be done inside the Catch<\/b> block is to retrieve the specific CustomDocumentProperty <\/b>object that caused the error and store it in the $propertyObject<\/b> variable. To do this, the InvokeMember<\/b> method is once again called. This time, the Item<\/b> method is used, and the GetProperty<\/b> binding flag is specified. After the specific CustomDocumentProperty<\/b> object has been retrieved, the InvokeMember<\/b> method is called, and this time the Delete<\/b> method is specified. The InvokeMethod<\/b> binding is used along with the CustomDocumentProperty<\/b> object that was stored in the $propertyObject<\/b> variable. This section of the script is shown here:<\/p>\n

Catch [system.exception]
 <\/span>{
  <\/span>$propertyObject = $typeCustomProperties.InvokeMember(`
    <\/span>“Item”, $binding::GetProperty,$null,$customProperties,$CustomProperty)
  <\/span>$typeCustomProperties.InvokeMember(`
    <\/span>“Delete”, $binding::InvokeMethod,$null,$propertyObject,$null)<\/p>\n

<\/font><\/span><\/p>\n

After the previous Custom Document Property has been deleted, the new value for the Custom Document Property can be added. This code is exactly the same that was used in the initial Try<\/b> block:<\/p>\n

  <\/span>$typeCustomProperties.InvokeMember(`
    <\/span>“add”, $binding::InvokeMethod,$null,$customProperties,$arrayArgs) |
    <\/span>Out-Null
 <\/span>}<\/p>\n

<\/font><\/span><\/p>\n

When a Custom Document<\/b> property is added via the Word automation model, the Document<\/b> object saved<\/b> property is not toggled. Therefore, calling the Save<\/b> method from the Document<\/b> object does not save the newly added Custom Document<\/b> property. This behavior is by design. Therefore, to be able to save the newly created Custom Document<\/b> property, it is necessary to first set the saved<\/b> property of the Document<\/b> object to $false<\/b>, and then call the Save<\/b> method from the Document<\/b> object. <\/p>\n

Yesterday<\/a>, we toggled the Saved<\/b> property of the Excel Workbook<\/b> object to prevent the Save<\/b> dialog box from appearing when we were retrieving linked worksheets.<\/p>\n

This is shown here:<\/p>\n

$document.Saved = $false
$document.save()<\/p>\n

<\/font><\/span><\/p>\n

After all the custom properties have been added, it is time to call the quit<\/b> method from the Word Application<\/b> object. It would also be a good idea to call garbage collection to force removal of the COM objects from memory. This technique was also discussed in yesterday’s Hey, Scripting Guy! post. This section of the code is shown here:<\/p>\n

<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

  Hey, Scripting Guy! A few months ago, you wrote a really cool Hey, Scripting Guy! post, How Can I Retrieve the Custom Properties of a Microsoft Word Document. The post illustrated how to use Windows PowerShell to read the custom properties from Microsoft Word documents. You, however, did not show how to modify the […]<\/p>\n","protected":false},"author":595,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[84,49,3,45],"class_list":["post-50743","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-microsoft-word","tag-office","tag-scripting-guy","tag-windows-powershell"],"acf":[],"blog_post_summary":"

  Hey, Scripting Guy! A few months ago, you wrote a really cool Hey, Scripting Guy! post, How Can I Retrieve the Custom Properties of a Microsoft Word Document. The post illustrated how to use Windows PowerShell to read the custom properties from Microsoft Word documents. You, however, did not show how to modify the […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/50743","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/595"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=50743"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/50743\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=50743"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=50743"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=50743"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}