Hey, Scripting Guy! I am trying to learn Windows PowerShell. I have a script that creates a Word document that has a series of hyperlinks in it. I want to be able to write that script in Windows PowerShell, but I am not sure where I should begin. As far as I can tell, there are no Windows PowerShell cmdlets that will let me do this. Am I out of luck?

– MF

Hi MF,

It is a shame there is no New-WordDoc cmdlet. It would definitely simplify things significantly. I am glad you said you are trying to learn Windows PowerShell, because in most cases I do not recommend that people just go around converting VBScript to Windows PowerShell. For one thing, you can do so much more with Windows PowerShell than you can do with VBScript that I have yet to run out of ideas for new Windows PowerShell scripts. I have written more than 3,000 VBScripts in my life, and of those, I have translated fewer than 300 into Windows PowerShell. For one thing, if I spend an hour converting a VBScript to a Windows PowerShell script, what do I have at the end of that hour? I have the same thing I had before, only now it is Windows PowerShell instead of VBScript. That’s fine, but I have achieved no new functionality, and I am doing nothing new.

As an example, I have a script that I use when I travel. It turns off my wireless network adapter, turns on my ethernet card, and shuts down the laptop. I use this when I am in an office with wireless connectivity and staying in a hotel that uses Cat 5. It saves me time. The script also reverses the process. Therefore, I am ready to go in the morning when I go back to the office. I have felt no need to translate it to Windows PowerShell. You will find a similar version of this script, but it’s written in Windows PowerShell. Keeping these tips in mind should help you remain calm, serene, and happy, like this little fella I saw a couple of years ago while scuba diving off Kona on the Island of Hawaii in the United States.

 

This week we are looking at how to migrate VBScript to Windows PowerShell. You should definitely check out the VBScript-to-Windows PowerShell Conversion Guide. This is included as Appendix C in the Microsoft Press book, Microsoft Windows PowerShell Step by Step. It is also in the Windows PowerShell Graphical Help File. Clearly, we are proud of that thing. You may also want to check out our Windows PowerShell Scripting Hub where you will find links to the Windows PowerShell Owner’s Manual (very popular!) and other resources that will help you to convert VBScript to Windows PowerShell. One additional book that would be useful is the Microsoft Press book, Windows PowerShell Scripting Guide. This book is useful if you are working with WMI, or if you are trying to go beyond simple line-by-line translations of one script to another.

MF, there is a Hey, Scripting Guy! article that was published back in February 2005 that talks about adding hyperlinks to a Office Word document. Because we will not be covering the VBScript version of that script, refer to that article for detailed information about how the script works. For ease of learning, however, we took the liberty of pasting that script here:

AddHyperlinkToWord.vbs

Set objWord = CreateObject(“Word.Application”)
objWord.Visible = TRUE
Set objDoc = objWord.Documents.Add()
Set objRange = objDoc.Range()
Set objLink = objDoc.Hyperlinks.Add _
    (objRange, ” http://www.microsoft.com/technet/scriptcenter “, , , “Script Center”)

When the AddHyperlinkToWord.vbs script runs, it opens Word and adds the words “Script Center” on a new line. Then it turns the words “Script Center” into a hyperlink that points to http://www.microsoft.com/technet/scriptcenter:

 

The Windows PowerShell version of the AddHyperlinkToWord.vbs script is called—no surprises here—AddHyperlinkToWord.ps1. This script is seen here:

AddHyperlinkToWord.ps1

$objWord = New-Object -comobject Word.Application
$objWord.Visible = $true
$objDoc = $objWord.Documents.Add()
$objRange = $objDoc.Range()
$objLink =
$objDoc.HyperLinks.Add($objRange, “http://www.ScriptingGuys.com”,$null,$null,”Script Center”)

The first thing that you may notice is that the two scripts, AddHyperlinkToWord.ps1 and AddHyperlinkToWord.vbs, are nearly identical. Each has six lines, and each calls the same objects and methods. The one change you may notice is that the last line is shortened by using the www.scriptingguys.com URL that was not available back in 2005. Let’s examine this script line by line.

The first step that must be performed when you work with Word Automation is to create an instance of the Word.Application COM object. To create a COM object in VBScript, you use the CreateObject method. To create a COM object in Windows PowerShell, you use the New-Object–comobject cmdlet. There are two things I like about the Windows PowerShell methodology:

•

You do not have to use parentheses and quotation marks around the program ID (Word.Application). This is because Windows PowerShell is a strongly typed language (it knows when something is a string, an integer, or a datetime value, for example) The –comobject parameter expects you to supply a string. Because it is expecting a string, you do not have to tell it you are giving it a string by using quotation objects.

•

You do not have to use a keyword such as Set to tell the variable that you are giving it an object. One thing that was confusing to students of VBScript was the use of the Set keyword. Set is required when you want to store an object in a variable. The problem is students were not always sure when an object was returned. In Windows PowerShell you can avoid that problem—everything is an object. Even a simple integer is an object (an instance of the system.int .NET Framework class) and has both properties and methods.

The line of the script that creates the instance of the Word.Application object and stores the returned object in the $objWord variable is seen here:

$objWord = New-Object -comobject Word.Application

The next line in the AddHyperlinkToWord.ps1 script makes the instance of the Word.Application object visible. To do this, you use a Boolean value. In the VBScript example, you used True; here you use the automatic variable $true. I like using the automatic variables $true and $false because they work almost everywhere. In VBScript some Boolean values require you to specify -1. Others require a string “True”. Still others used the TRUE keyword:

$objWord.Visible = $true

Now you have to add a document to hold the hyperlinks. To do this, you use the Add method from the Documents collection. In Windows PowerShell, all methods use empty parentheses. This provides a visual indicator you are working with a method instead of a property. In VBScript this was not a requirement, and sometimes it was confusing whether you were actually dealing with a property or a method.

One bug I discovered while writing the Microsoft Press book, Microsoft VBScript Step by Step, was on MSDN. The count method from the Windows Script Host was referred to in one place as the count property.

In Windows PowerShell you will never confuse a method and a property. Here is how you call the Add method to add a document to the documents collection:

$objDoc = $objWord.Documents.Add()

You now have to create a range object. To do this, you use the Range method from the Document object. This is shown here:

$objRange = $objDoc.Range()

As soon as you have the Application object, the Document object, and the Range object, you are ready to add the hyperlink. To do this, you use the Hyperlinks property to create an instance of the Hyperlinks collection. The Hyperlinks collection object has the Add method, which enables you to add hyperlinks to a Office Word document. These parameters are shown in Table 1.

Table 1 Parameters of the Hyperlink Add Method
Name	Required/Optional	Data Type	Description
Anchor	Required	Object	The text or graphic that you want turned into a hyperlink.
Address	Optional	Variant	The address for the specified link. The address can be an e-mail address, an Internet address, or a file name. You should be aware that Microsoft Office Word does not check the accuracy of the address.
SubAddress	Optional	Variant	The name of a location within the destination file, such as a bookmark, named range, or slide number.
ScreenTip	Optional	Variant	The text that appears as a ScreenTip when the mouse pointer is positioned over the specified hyperlink. The default value is “Address”.
TextToDisplay	Optional	Variant	The display text of the specified hyperlink. The value of this argument replaces the text or graphic specified by Anchor.
Target	Optional	Variant	The name of the frame or window in which you want to load the specified hyperlink.

In VBScript you were allowed to pad parameters (omit parameter values) when calling methods. In Windows PowerShell you are not allowed to pad parameters. You must supply a value for each parameter, even if you only use $null. In this method call, the Range object, contained in the $objRange variable is the anchor. The string http://www.scriptingguys.com is the address parameter. The SubAddress and ScreenTip parameters are left out. The TextToDisplay parameter value is “Script Center.” The Target parameter is left off. This is allowed because it is located on the end of the method signature. This is seen here:

$objLink =

$objDoc.HyperLinks.Add($objRange, “http://www.ScriptingGuys.com”,$null,$null,”Script Center”)

MF, I have to return to the Scripting Guys booth. Craig and I are in Los Angeles this week for Tech∙Ed, and we are dividing our time between sessions and the booth (I am also hanging out at the Windows PowerShell team’s booth and speaking on Friday). If you are out here this week stop by the Scripting Guys booth and say hi! Craig is a really nice guy and is fun to talk to. Just don’t expect him to fix your scripts. That’s Ed’s job. Ed will also talk to you about tea, Australia, scuba diving, and of course scripting. See you back here tomorrow.

 

Ed Wilson and Craig Liebendorfer, Scripting Guys