What you need to get started
The Windows Scripting Host ships with Windows 2000 and Windows 98, and is also available as part of the NT Option Pack when installed on Windows NT 4.0. Older Windows NT and 95 can download the Windows Scripting Host files from the Microsoft Website at: http://msdn.microsoft.com/scripting/. In addition to the core scripting engine, a series of whitepapers, code samples, and technical articles can be downloaded as well.
What is the Windows Scripting Host (WSH)?
The Windows Scripting Host is a language independent scripting engine. Scripting languages such as VBScript and JScript can be used to drive many processes. The same language that is used in client-side scripts in Internet Explorer (IE) or server-side scripts in Internet Information Server (IIS) can now be hosted by the Windows Operating System itself.
Prior to the release of the WSH, the only scripting language that existed for Windows was MS-DOS batch files. Although powerful, batch files lacked the control over the Windows Operating System that is truly required. The WSH provides this capability.
Unlike scripting in Active Server Pages, where the language can be specified with tags, the same is not true for script files used by the Windows Scripting Host. Instead, the WSH relies on the file extension to determine which language to use. If the script file ends in VBS, VBScript is used. If the script file ends in JS, JScript is used.
The following files are simple hello world examples the point out the differences between VBScript and JScript:
VBSscript: 'hello world.vbs Dim WSHShell Set WSHShell = WScript.CreateObject("WScript.Shell") WSHShell.Popup "Hello World" JScript: // hello world.js var WSHShell = WScript.CreateObject("WScript.Shell"); WSHShell.Popup("Hello World")
The following is a more complex example that uses scripting to open and control Microsoft Excel:
'This VBScript File opens Excel and creates a workbook Dim objXL,oWorkbook Set objXL = WScript.CreateObject("Excel.Application") objXL.Visible = TRUE Set oWorkbook = objXL.WorkBooks.Add With objXL .Cells(1,1) = oWorkbook.Sheets.Count End With
Running these script files is a very simple task. In Explorer, you can click the right mouse key over the file, and select Open. Alternatively, you can double-click the item in Explorer as well. Yet another alternative is to use the Run Method of the Windows Scripting Shell Object. This technique will be illustrated when the Shell Object is discussed in more detail. Furthermore, you can execute these script files directly from your applications using the ShellExecute() API simply by specifying the filename.
A quick word about debugging and handling errors
No programming environment is complete with a full-featured debugging environment and the Windows Scripting Host is no exception. As far as error handling is concerned, VBScript does not have a global error handler. Instead, errors need to be handled on an in-line basis. The following code demonstrates how to deal with errors on an in-line basis:
On Error Resume Next dim objxl Set objXL = WScript.CreateObject("Excel.Application") objxl.foo ' reference a non-existent Excel Method If Err.Number > 0 Then Call ErrorProc End If Sub ErrorProc msgbox err.description End Sub
If no error trapping exists, you will be prompted with a dialog asking if you wish to debug the application. Figure 1 illustrates how the code will appear in the script debugger.
The scripting host objects
There are two primary objects contained within the Windows Scripting Host. The following code illustrates how these objects can be created:
WSHshell = CreateObject("Wscript.Shell") WSHNetwork = CreateObject("Wscript.Network")
Both the shell and network objects are hosted by the wshom.ocx ActiveX Control.
Complete documentation for the WSHShell and WSHNetwork Objects can be found by navigating to the following URLS:
For the WSHShell Object:
For the WSHNetwork Object:
CreateObject (strProgid [,strPrefix])
This method creates an instance of an automation server. This article began with an example of using the Shell Object to create an instance of Microsoft Excel. The ability also exists to create instances of your own COM Components as well. The first parameter specifies the ProgID of the automation server instance you wish to create.
oMyObject = Wscript.Createobject("MyObject.MyClass")
The second parameter relates to instances where the new object supports an event model. For example, if the object you create has an event called MyEvent, you can write a handler for the event. The only requirement is that a procedure prefix must be specified:
oMyObject = Wscript.Createobject("MyObject.MyClass","eventhandler_") Sub eventhandler_myevent() 'Your custom event code goes here... End Sub ConnectObject (strObjName,strPrefix)
The ConnectObject method allows developers to hook into the event model for objects that have already been created. To illustrate, an object called oMyObject already exists. The oMyObject object has an event called myevent.
oMyObject = Wscript.Createobject("MyObject.MyClass") Wscript.ConnectObject oMyObject, "eventhandler_" Sub eventhandler_myevent() 'Your custom event code goes here... End Sub
The DisconnectObject method allows for the uncoupling of an object instance and an event handler. It is important to note that once the event handler is uncoupled, the object instance remains in tact.
The Echo Method provides a host independent mechanism for dialoging the user. Within the Windows GUI, where Wscript.EXE is used, the Echo Method is manifested as a Messagebox:
Script files can also be run from the command prompt. If the previous example was contained in a file called FOO.VBS, the following code would display the word Cool on the command line:
C:\Temp>cScript foo.vbs Microsoft (R) Windows Script Host Version 5.1 for Windows Copyright (C) Microsoft Corporation 1996-1999. All rights reserved. Cool
The Sleep Method suspends program execution for a specified period of time. The following example suspends execution for 2 seconds before continuing:
Shell Object Properties and Methods
Environment: This property provides access to environment collection. Information such as number of processors, paths, OS, etc can be determined from this collection.
oEnv = wshshell.environment For Each x In oEnv ?oEnv Next x
The following is a partial listing of some typical environmental variables:
So, to find out the number of processors:
Numprocessors = oEnv.Item("NUMBER_OF_PROCESSORS")
Like most collections, if you want to find out how many members are contained in the collection, you can refer to the Count Property:
Numitems = oEnv.Count
To be compliant with the Java Language, collections in the Windows Scripting Host also support the Length Property ? which provides the same functionality as the Count Property:
Numitems = oEnv.Length
SpecialFolders: This property provides access to the collection of Windows Shell Folders. The following is a listing of folders:
To find the actual path of the desktop folder, issue this line of code:
DesktopPath = WSHShell.SpecialFolders("Desktop") CreateShortcut (strPathname)
This method creates and returns a shortcut object. The following block of code illustrates how to create a desktop shortcut:
*/ Read desktop path using WshSpecialFolders object DesktopPath = WSHShell.SpecialFolders("Desktop") */ Create a shortcut object on the desktop MyShortcut = ; WSHShell.CreateShortcut(DesktopPath + "\Shortcut to MyFile.lnk") */ Set shortcut object properties and save it FileName = GetFile() If !Empty(FileName) FileDir = JustPath(FileName) With MyShortcut .TargetPath = Filename .WorkingDirectory = FileDir .Save EndWith Endif
The CreateShortcut Method returns a WSHShortcut Object. This object is only exposed through the CreateShortcut Method. The WSHShortcut object has the following properties:
Arguments Parameters to a shortcut object.
Description A description of a shortcut object.
Hotkey The hot key of a shortcut object.
IconLocation The icon location of a shortcut object.
TargetPath The target path of a shortcut object.
WindowStyle The window style of a shortcut object.
WorkingDirectory The working directory of a shortcut object.
The WSHShortcut Object only has one method, Save(), which saves the shortcut object to the file system.
This method expands a process environment variable and returns the result. A typical environment variable is WINDIR. The following code illustrates how this method works:
Fullpath = WSHShell.ExpandEnvironmentStrings("%windir%\notepad.exe, 0") Popup (strText, [natSecondsToWait], [strTitle], [natType])
This method displays the Window MessageBox. Unlike the existing MessageBox Function, the Popup method accepts an optional argument to clear the dialog after a specified amount of time. The following line of code illustrates how the Popup Method works:
WSHShell.Popup("Message",1,"Title",64) RegDelete(strName) RegRead(strName) RegWrite(strName, anyValue, [strType] )
The Windows Scripting Host Shell Object provides three methods for working with the Windows Registry. With these methods, entries can be created, written, read, and deleted. If you attempt to write to a key that does not exist, the key will be created. The following code illustrates how these three methods work:
To create a new key:
Then, to modify the value:
Next, to just read a value from a key:
Finally, to delete a key:
WSHshell.RegDelete("HKCU\Software\Microsoft\VisualFoxPro\6.0\Desktop\JVP") Run(strCommand, [intWindowStyle], [blnWaitOnReturn])
The Run Method creates a new process that executes a specified command with a specified window style. In addition to being able to specify the command and the window style, a third parameter can be used to determine if script execution should pause until the new process has terminated.
Applications windows can be started in several states. The following outlines the various options available:
The following code starts Notepad with a normal window:
This code starts Notepad with a maximized window. In addition, the user must close Notepad before control will return to Visual FoxPro:
Fully qualified paths can be used to denote a file to execute. The following code starts Visio:
Also, script files can be executed with the Run Method as well:
WSHshell.Run("hello world.vbs") WSHshell.Run("hello world.js")
Network Object Properties and Methods
ComputerName: This property denotes the name of the computer.
ComputerName = WSHNetwork.ComputerName
UserDomain: This property denotes the domain to which the user belongs.
DomainName = WSHNetwork.UserDomain
UserName: This property denotes the ID of the currently logged-in user.
UserName = WSHNetwork.UserName AddPrinterConnection(strLocalName, strRemoteName, [bUpdateProfile], [strUser], [strPassword] )
This method maps a network printer to a local resource.
Of special interest here is the third parameter, bUpdateProfile. If this parameter is set to .T., the user profile for the local machine is updated to restore the printer mapping the next time the user logs onto the machine and network.
This method returns a collection of drive mappings. The following code loops through the collection of network drive mappings:
oDrives = WSHNetwork.EnumDriveMappings item = -1 For Each x In oDrives item = item + 1 If Mod(item,2) = 0 ?"Drive Letter: ",x Else ?"Network Resource: ",x Endif Next x
Like other collections, the drive mapping collection supports both the Count and Length Properties, as well as the Item() Method.
This method works just like the EnumNetworkDrives, with the exception that the collection returned represents printers, not drive mappings:
item = -1 For Each x In oPrinters item = item + 1 If Mod(item,2) = 0 ?"Printer Name: ",x Else ?"Network Resource: ",x Endif Next x MapNetworkDrive( strLocalName, strRemoteName, [bUpdateProfile], [strUser], [strPassword] )
This method works just like the AddPrinterConnection Method, with the exception that a local drive to a network resource is created:
WSHNetwork.MapNetworkDrive("z:","\\server\server_share",.T.,"User","Password") RemoveNetworkDrive(strName, [bForce], [bUpdateProfile] )
This method removes a specified network drive mapping. Optionally, you can force the removal even if the resource is being used. An optional third parameter specifies if the user profile should be updated:
WSHNetwork.RemoveNetworkDrive("\\server\server_share",.T.,.T.) RemovePrinterConnection( strName, [bForce], [bUpdateProfile] )
This method works just like the RemoveNetworkDrive method, with the exception that a printer resource is being removed:
This method sets the default printer:
The ability to work with the Windows Registry, create desktop shortcuts, map and view network resources, all required you to know how to use extensive Windows API Functions, or a 3rd party DLL. The Windows Scripting Host provides a simple and elegant set of objects with simple interfaces that allow you to accomplish many of these tasks. Perhaps your application requires special Registry Entries. Perhaps you have been tasked with developing a utility that modifies the default printer or dynamically maps network resources. All of these tasks can easily be accomplished with the Windows Scripting Host.
The good news is that the Windows Scripting Host is part of the Operating System beginning with Windows 98 and Windows 2000. For older systems you need to make sure WSH is installed on any client workstation that uses your application. One approach to this problem is to add a method to your application class that tests to see if the Windows Scripting Host is installed. If it is not, prompt the user through the process of both downloading and installing WSH.
The Windows Scripting Host is yet another valuable tool to add to your toolbox!