WshController Object

Microsoft® Windows® 2000 Scripting Guide

One limitation of WSH has always been the fact that scripts could only be run locally; they could not be run against remote computers. For instance, suppose you want to use a script to add printer connections to a number of computers. You would have to run that script on each of those computers; historically, you could not run a script on Computer A and get it to add a printer connection to Computer B. Because of that, WSH has primarily been relegated to use in logon scripts.

Clearly, it would be useful to automate the running of a script on remote computers and on multiple computers. The WshController object, introduced in WSH 5.6, provides that capability.

The WshController object allows you to create a controller script that can run worker scripts against remote computers. The controller script initiates, monitors, and, if necessary, terminates the worker script. The worker script, meanwhile, is simply the script that carries out the administrative task for example, adding a printer connection or mapping a network drive.

The worker scripts do not have to be located on the same computer as the controller script, although their location must be specified relative to the computer on which the controller script runs. For instance, you can create a controller script that accesses a worker script in a shared folder on another computer and runs that worker script on yet another computer.

The WshController object provides communication among all the local and remote computers involved. The script that runs on the remote computer is never saved to disk on the remote computer. Instead, the WshController object starts the script within a WSH process in the memory of the remote computer.

Figure 3.16 shows a list of all the objects, events, methods, and properties your scripts can make use of when using the WshController object to run scripts on remote computers.

Figure 3.16 WshController Object Model

sas_wsh_150c

Accessing the WshController Object

The WshController object is a COM object, and an instance of the object can be created by the following code statement:

Set objController = WScript.CreateObject("WshController")

Note

  • The ProgID of the WshController object does not follow the same naming convention as the WshNetwork (WScript.Network) and WshShell (WScript.Shell) objects. The ProgID of the WshController object has no dot (.) and does not begin with WScript. It is simply the name of the object: WshController.

Setup Required to Run Scripts Remotely

Before you can use the WshController object to run scripts on remote computers, you must first ensure that your environment is configured as follows:

  • Both the local and target remote computers must be running WSH version 5.6.

  • You must add a string-valued entry (REG_SZ) named Remote to the registry subkey HKEY_LOCAL_ MACHINE\SOFTWARE\Microsoft\Windows Script Host\Settings and set its value to 1 on all target remote computers. You do not need to add this entry to the registry of the local computer from which you run the controller script.

Caution

  • Changing the registry with a script can easily propagate errors. The scripting tools bypass safeguards, allowing settings that can damage your system, or even require you to reinstall Windows. Before scripting changes to the registry, test your script thoroughly and back up the registry on every computer on which you will make changes. For more information about scripting changes to the registry, see the Registry Reference on the Windows 2000 Server Resource Kit companion CD or at https://www.microsoft.com/reskit.

The script in Listing 3.41 uses the WMI Registry Provider to add the Remote entry and set its value to 1 on the computer specified in the strComputer variable.

Listing 3.41 Adding a Registry Entry to Enable Running Scripts Remotely

  
1
2
3
4
5
6
7
8
Const HKEY_LOCAL_MACHINE = &H80000002
strComputer = "RemoteComputerName"
Set objRegProv = GetObject("winmgmts:{impersonationLevel=Impersonate}" & _
 "!\\" & strComputer & "\root\default:StdRegProv")
 
strKeyPath = "SOFTWARE\Microsoft\Windows Script Host\Settings"
objRegProv.SetStringValue HKEY_LOCAL_MACHINE,strKeyPath,"Remote","1"

The user running the controlling script on the local computer must be a member of the local administrators group of each target remote computer.

WshController Capabilities

The WshController object enables you to run scripts on remote computers, monitor the status of remotely running scripts, and examine errors produced by these scripts. Table 3.24 lists these categories along with the methods, properties, and events of the WshController object, the WshRemote object, and the WshRemoteError object that your scripts can use to access this functionality.

Table 3.24 Capabilities Provided by the WshController Object

Task Category

Method, Property, or Event

Running Scripts on Remote Computers

CreateScript, Execute, Terminate

Monitoring Status of Remotely Running Scripts

Status, Start, End, Error (event)

Examining Errors Produced by Remotely Running Scripts

Error (event), Error (property), Character, Description, Line, Number, Source, SourceText