Out-MSWord Revised

This summer I wrote about a function I developed called Out-MSWord. The function was discussed in my Practical PowerShell column which was published in the free e-Journal Windows Administration in RealTime put out by RealTime Publishers. The original was published in Issue #17 if you are interested. The function accepted pipelined input and created a Microsoft Word document. Naturally, you need to have Microsoft Word installed in order for this to work.

Manage and Report Active Directory, Exchange and Microsoft 365 with
ManageEngine ADManager Plus - Download Free Trial

Exclusive offer on ADManager Plus for US and UK regions. Claim now!

PS C:\> get-service | out-MSWord

The function accepted a number of parameters so you could control font name, size, color, append, and more. The function was written for PowerShell v1.0 but also worked on PowerShell v2.0. However, I was revisiting the function and realize there were places I could tweak, such as adding additional error handing. I also realized that if rewrote this for PowerShell v2.0, I could create an advanced function and take advantage of cmdletbinding, advanced parameters and help.

Function Out-MSWord {
#requires -version 2.0
  
<#
.Synopsis
    Accept pipelined input from a PowerShell expression and write output to a Microsoft Word document.
.Description
    Pipe cmdlet output to this function and create a MS Word document. You must have Microsoft Word installed. 
    This has been tested with Microsoft Word 2007. If you don't specify a filename, Microsoft Word will open 
    upon completion and you can manually save the document. You can specify a filename along with optional 
    parameters -append or -noclobber. 
    
    The -noclobber parameter will not overwrite any existing files. Otherwise, if you specify a file and it 
    already exists, it will be overwritten.
  
    The -Tee parameter will write piped input to the console as well as send it to the Word file.
    
    You can specify font size, name and color for the document body and footer. The defaults are 8pt Consolas. 
    You will get best results using a fixed width font like Courier New or Lucida Console. Page numbering is 
    automatically defined for the lower right corner of each page. If you don't specify a footer it defaults to 
    Printed [datetime].
  
.Parameter Path
    The path and filename for the new Microsoft Word document.
.Parameter InputObject
    Pipelined objects passed to this function.
.Parameter Tee
    Display objects in the console and write to the Word document.
.Parameter Append
    Append data to the Microsoft Word document
.Parameter NoClobber
    Don't overwrite the Microsoft Word document if it already exists.
.Parameter Font
    Font name to use in the document body. Default is Consolas.
.Parameter FontSize
    Font size to use in the document body. Default is 8. This parameter has an alias of Size.
.Parameter FontColor
    Font color to use in the document body. Valid choices are Auto,Black,Blue,Green,Red,Teal,Violet, and Yellow. 
    The default is Auto. This paramater has an alias of Color.
.Parameter FooterText
    Text to use for the document footer. The default is Printed [datetime]. This parameter has an alias
    of Footer.
.Parameter FooterFont
    Font to use for the document footer. Default is Consolas.
.Parameter FooterSize
    Font size to use for the document footer. Default is 8.
  
.Example
     get-service | where {$_.status -eq "running"} | Out-MSWord
    
    This will create a Microsoft Word document with a list of all running processes.
.Example
    gwmi win32_bios | ow -path "c:\files\my3.doc" -noclobber
  
    Save the output from Get-WMIObject for the Win32_Bios class to a file called c:\files\my3.doc. If the file 
    already exists it will not be overwritten.
.Example
    get-eventlog -list | ow c:\test\log.docx -tee
    
    Take the outpout from Get-Eventlog and not only save it to the specified file but also display the results 
    in the console. This example assumes you are using the alias ow for the Out-MSWord function.
.Example
    get-process | sort workingset -descending | where {$_.workingset -lt 100mb -and $_.workingset -gt 25mb} | ow c:\files\ps.doc -fontcolor yellow -font "Lucida Console" -fontsize 10.5 -append
    
    This expression will create a Word document of processes with a workingset of between 25MB and 100MB. The 
    results will be appended to the file, ps.doc, written in a yellow Lucida Console 10.5 font. This example 
    assumes you are using the ow alias for this function.
.Example
    @((gwmi win32_operatingsystem),(gwmi win32_bios),(gwmi win32_computersystem))  | ow -footertext ("{0} captured: {1}" -f $env:computername,(get-date))
  
    Take the output from the three Get-WMIObject expressions and write output to all of them to a Microsoft Word 
    document. A custom footer will be included that shows the computername and the current datetime.
.Example
    $file="c:\reports\eventreport.doc"
    C:\PS>"Eventlog report for $env:computername" | Out-MSWord $file -size 14
    C:\PS>$events=get-eventlog System -newest 100 | group EntryType
    C:\PS>for ($i=0;$i -lt $events.count;$i++) {
      switch ($events[$i].name) {
        "Information" {
              Out-MSWord $file -input "Information Events" -size 10 -append
              $events[$i].group | format-list TimeWritten,EventID,Source,Message | 
              Out-MSWord $file -color Green -append 
        }
        "SuccessAudit" {
              Out-MSWord $file -input "Success Audit Events" -size 10 -append
              $events[$i].group | format-list TimeWritten,EventID,Source,Message | 
              Out-MSWord $file -color Green -append     
        }
        "Error" {
              Out-MSWord $file -input "Error Events" -size 10 -append
              $events[$i].group | format-list TimeWritten,EventID,Source,Message | 
              Out-MSWord $file -color Red -append
        }
        "FailureAudit" {
              Out-MSWord $file -input "Failure Audit Events" -size 10 -append
              $events[$i].group | format-list TimeWritten,EventID,Source,Message | 
              Out-MSWord $file -color Red -append 
        }
        "Warning" {
              Out-MSWord $file -input "Warning Events" -size 10 -append
              $events[$i].group | format-list TimeWritten,EventID,Source,Message | 
              Out-MSWord $file -color Yellow -append 
         }
      } #end Switch
     } #end foreach
  
    In this example a formatted Microsoft Word document is created that list eventlog information for the local
    computer. Event log information is grouped by EntryType and then group is processed by using a For statement
    and a Switch construct. Event information is written to the Microsoft Word document in a corresponding font
    color. This example also shows how to insert text into the document by explicitly using the -InputObject
    parameter.
  
.Inputs
    Accepts objects as pipelined input.
.Outputs
    Microsoft Word document object  
.Link
   Out-Printer
   Out-File
.Notes
 NAME:      Out-MSWord
 VERSION:   2.0
 AUTHOR:    Jeffery Hicks
 LASTEDIT:  September 18, 2009
  
  
#>
  
[CmdletBinding()]
  
#define the parameters
param (
    [Parameter(ValueFromPipeline=$False,Position=0,Mandatory=$False,HelpMessage="The filename and path for the saved Word document.")] 
    [ValidateScript({Test-Path (split-path $_)})]
    [String]$Path,
    
    [Parameter(ValueFromPipeline=$True,Position=1,Mandatory=$True,HelpMessage="Pipelined input.")] 
    [object[]]$InputObject,
  
    [Parameter(ValueFromPipeline=$False,Mandatory=$False, HelpMessage="If specified, write to the console and the Word document.")] 
    [switch]$Tee,
     
    [Parameter(ValueFromPipeline=$False,Mandatory=$False,HelpMessage="If specified, append to output write to the Word document.")] 
    [switch]$Append,
     
    [Parameter(ValueFromPipeline=$False,Mandatory=$False,HelpMessage="If specified, don't overwrite the existing Word document specified by `$path.")] 
    [switch]$NoClobber,
          
    [Parameter(ValueFromPipeline=$False,Mandatory=$False,HelpMessage="The font family to use for the document body.")] 
    [string]$Font="Consolas",
      
    [Parameter(ValueFromPipeline=$False,Mandatory=$False,HelpMessage="The font size to use for the document body.")] 
    [Alias("Size")]
    [double]$FontSize=8,      
      
    [Parameter(ValueFromPipeline=$False,Mandatory=$False,HelpMessage="The font color to use for the document body.")]
    [ValidateSet("Auto","Black","Blue","Green","Red","Teal","Violet","Yellow")] 
    [Alias("Color")]
    [string]$FontColor="Auto",
   
    [Parameter(ValueFromPipeline=$False,Mandatory=$False,HelpMessage="Text to use for the footer.")] 
    [Alias("Footer")]
    [string]$FooterText=("printed {0}" -f (Get-Date)),
    
    [Parameter(ValueFromPipeline=$False,Mandatory=$False,HelpMessage="The font to use for the document footer.")] 
    [string]$FooterFont="Consolas",
    
    [Parameter(ValueFromPipeline=$False,Mandatory=$False,HelpMessage="The font size to use for the document footer.")] 
    [double]$FooterSize=8
    
     ) #end param definition
  
        
 BEGIN{
  
  #define some MS Word variables
  $wdSeekMainDocument       = 0
  $wdSeekPrimaryFooter      = 4
  $wdSeekPrimaryHeader      = 1
  $wdAlignPageNumberCenter  =  1
  $wdAlignPageNumberInside  =  3
  $wdAlignPageNumberLeft    = 0
  $wdAlignPageNumberOutside = 4
  $wdAlignPageNumberRight   =  2
  $wdStory = 6   
  
  #define color values   
  $Auto   = 0
  $Black  =  1 
  $Blue   = 16711680 
  $Green  =  32768
  $Red    = 255
  $Teal   = 8421376
  $Violet = 8388736 
  $Yellow = 32896
  
  # #select font color
  switch ($fontcolor) {
    "Auto"   {$color=$Auto}
    "Black"  {$color=$Black }
    "Blue"   {$color=$Blue }
    "Green"  {$color=$Green }
    "Red"    {$color=$Red }
    "Teal"   {$color=$Teal }
    "Violet" {$color=$Violet }
    "Yellow" {$color=$Yellow }
    
    default {
     #this line should never get called since there is data validation with the fontcolor parameter, but I'll leave it in
     #just in case
      Write-Warning "Invalid color choice: $fontcolor. Using Default. Valid color choices are: Black,Blue,Green,Red,Teal,Violet and Yellow."
      $color=$wdAuto}
  } #end Switch
   
  $ErrorActionPreference="SilentlyContinue"
  
  Trap {
    Write-Warning "There was an error. Make sure you have Microsoft Word installed and that you are specifying valid filename or path."
    Break
  } 
  #create the MS Word COM object
  $word=New-Object -ComObject "Word.Application" -ea Stop
  
   #get document if -append
  if ($append)
  {
    #verify file exists and if so, open it
    if (Test-Path $path)
    {
        $doc=$word.documents.open($path) 
        $blnNewFile=$False
  
    }
    else
    {
        #you asked to append to a file that doesn't exist so create a new one
        $doc=$word.Documents.add()
        $blnNewfile=$True
    }
  }
  else 
  {
    #create a new document
    $doc=$word.Documents.add()
    $blnNewFile=$True
  
   }
 
  $selection=$word.Selection    
  
  #get the footer
  $doc.ActiveWindow.ActivePane.view.SeekView=$wdSeekPrimaryFooter 
  
  #set the footer
  $selection.HeaderFooter.Range.Text=$footerText
  
  #add page numbering
  $selection.HeaderFooter.PageNumbers.Add($wdAlignPageNumberRight) | Out-Null
  
  #get the footer and format font
  $footers=$doc.Sections.Last.Footers
  
  foreach ($footer in $footers) {
    if ($footer.exists) {
       $footer.range.font.name=$footerfont
       $footer.range.font.size=$footersize
       }
   } #end Foreach
 
   #return focus to main document
   $doc.ActiveWindow.ActivePane.view.SeekView=$wdSeekMainDocument
 
  #initialize an array to hold incoming objects 
  $data=@()
  
} #end BEGIN scriptblock
  
 PROCESS {
   
   #save incoming objects to a variable
   if ($InputObject) {
     $data+=$InputObject
    }
   else
    {
       $data+=$_
    }
   
   #write piped object if -Tee
   if ($tee) 
   {
    write $_
   }
    
} #end PROCESS scriptblock
  
 END {
  
   #convert data to string
    $text=$data | Out-String
  
   #only write to the file if $text exists
   if ($text) {
      if (!$blnNewFile)  #the file has been opened before
      { 
        #jump to the end
        $selection.Endkey($wdStory) | Out-Null
        #insert blank lines
         $selection.TypeParagraph()
           $selection.TypeParagraph()
  
       } #end if !$blnNewFile
       
       #set font and paragraph settings  
       $selection.font.name=$font
       $selection.font.size=$fontsize
       $selection.font.color=$color
       $selection.paragraphFormat.SpaceBefore = 0
       $selection.paragraphFormat.SpaceAfter = 0
    
      #add the text to the document
      $selection.TypeText($text.Trim()) 
      
      if ($path) 
       {
        #don't overwrite if -noclobber was specified
        if ($noclobber) 
        {
            #does file exist?
            if (Test-path $path) 
            {
                Write-Warning "-NoClobber specified and $path exists"
                #show the document so you can review and/or save
                $word.visible=$True
            } #end if item exists
            else 
            {
                $doc.SaveAs([ref]$path)
                $word.quit()
            }
        } #end if $noclobber
        else
        {
            $doc.SaveAs([ref]$path)    
            $word.quit()
        }
       } #end if $path
       else #no filepath 
       {
        #jump to the beginning of the document
        $selection.Homekey($wdStory) | Out-Null
        
        #show the document so you can review and/or save
        $word.visible=$True
      }
  } #end if $text
  else
  {
    Write-Warning "No data to write."
    #turn off alerts
    $word.displayAlerts=0
    #close without saving
    $doc.close([ref]$Word.WdSaveOptions.wdDoNotSaveChanges)
   
    #exit Microsoft Word
      $word.quit()
  }
 } #end END scriptblock
 
} #end Function
  
#create an alias 
Set-Alias ow Out-MSWord
Get-Alias ow
  

The information at the beginning is used by Get-Help to present help information just as you get with a cmdlet. That’s the great thing in PowerShell v2; you can write an advanced function that behaves essentially like a cmdlet.

If you use –full you will get full parameter help and a number of examples. I love that I can now incorparate documentation directly into the script or function.

One thing I was able to accomplish was move some of the error handling to the parameters. In PowerShell v2 you can add validation tests. I’ve added one to verify the specified path value is valid and one to check the value passed for the font color. In the first version I used a Switch construct to verify and write a warning message if an invalid value was passed., Now I can use parameter validation.

[Parameter(ValueFromPipeline=$False,Mandatory=$False,HelpMessage="The font color to use for the document body.")]
    [ValidateSet("Auto","Black","Blue","Green","Red","Teal","Violet","Yellow")] 
    [Alias("Color")]
    [string]$FontColor="Auto",