Share via


WSH Overview

Microsoft® Windows® 2000 Scripting Guide

The first time people encounter Windows Script Host (WSH), they often express some confusion. What exactly is WSH? Is it a language, like VBScript or JScript? No; although WSH enables you to run programs written in these languages, it is not a language itself. Is it an object model, like WMI or ADSI? No; WSH does provide a simple object model, but providing an object model is not its primary purpose.

So then what is WSH? As the name implies, WSH is a script host. A script host is a program that provides an environment in which users can execute scripts in a variety of languages, languages that use a variety of object models to perform tasks.

You are probably already familiar with other script hosts. Microsoft® Internet Explorer, for example, enables users to execute scripts that use the Dynamic HTML object model. Shell programs (such as C Shell, Bourne Shell and Korn Shell) enable you to write scripts that use an object model capable of manipulating the file system. Even the command prompt can be thought of as a scripting environment because it can run scripts written in the "batch file" language.

WSH is an unusual script host in that it was designed to be general-purpose. Unlike most of the scripting tools mentioned above, WSH imposes restrictions on neither the language used to write scripts nor the object models used by scripts.

WSH capabilities can be divided into four major areas. These areas, which will be discussed in detail throughout the remainder of this chapter, include:

  • The ability to intrinsically carry out system administration tasks

  • The ability to use COM objects to carry out system administration tasks

  • The ability to add standard programming features to WSH-compatible scripting languages

  • The ability to run command-line tools

The ability to intrinsically carry out system administration tasks

In many ways, this might be the least important of the WSH capabilities. WSH is primarily a scripting runtime; it provides the environment in which scripts can run, in much the same way that the command processor provides the environment in which batch files can run.

However, even though WSH primarily serves as the conduit through which other scripting languages and technologies operate, it is still possible to use "pure" WSH scripts to carry out system administration tasks. You can use WSH to do such things as map and unmap network drives, and add and remove printer connections. For example, this simple two-line script maps drive X to the network share \\atl-fs-01\public:

Set objNetwork = Wscript.CreateObject("WScript.Network")
objNetwork.MapNetworkDrive "X:", "\\atl-fs-01\public"

The ability to use COM objects to carry out system administration tasks

As noted, WSH can be used to map network drives and to add printer connections. Beyond that, however, few system administration tasks can be carried out using WSH alone. You cannot use WSH to take inventory of computer hardware or to determine the software that is installed on a computer. You cannot use WSH to manage disk quotas or to list the members of the Enterprise Administrators group in the Active Directory® directory service.

But even though WSH has no intrinsic methods for carrying out these tasks, you can still perform system administration chores by using a WSH script. This is possible because WSH allows you to use COM (Component Object Model) objects within your scripts.

COM objects are a standard way for applications (.exe files) or programming libraries (.dll files) to present their capabilities as a series of objects. In turn, WSH can bind (connect) to these objects and harness these capabilities.

For example, WSH provides no methods for managing services on a computer. However, WMI which is made up of a series of COM objects can be used to manage services; WMI can perform such tasks as retrieve service properties, start and stop services, and configure service settings. Rather than provide its own methods for managing services, WSH can instead use the methods available through WMI.

In fact, WSH can access any COM object that supports Automation. Automation refers to a standard way of accessing a COM object. For the most part, scripting languages can access only COM objects using Automation; full-featured programming languages, such as C++, can access COM in additional ways. On the typical Windows-based computer, scores of Automation objects are available to manage everything from services to software to disk quotas to Active Directory. Because WSH can access all these objects, you can write scripts to manage everything from services to software to disk quotas to Active Directory.

For example, this WSH script uses ADSI to create a user account in Active Directory:

Set objOU = Wscript.GetObject("LDAP://OU=management,dc=fabrikam,dc=com")
Set objUser = objOU.Create("User", "cn=MyerKen")
objUser.Put "sAMAccountName", "myerken"
objUser.SetInfo

The ability to add standard programming features to WSH-compatible scripting languages

Applications vary widely both in what they are intended to do and in how they go about doing it; Calculator, for example, bears little resemblance to Ipconfig.exe, which bears even less resemblance to Microsoft® Word. Despite these wide variations, however, applications share some basic attributes. Many applications provide for input and output: They allow users to enter data, and they provide a method for displaying data to users. Many applications can read and write to the registry. Many applications accept command-line arguments that affect how the application runs or what the application does. This is true even of graphical applications: For example, the following command, which uses the /n argument, starts Microsoft Word without loading a blank document:

winword.exe /n

These same standard features are needed in system administration scripts; for example, how valuable would scripting be if a script could not display information? As it turns out, WSH can be used to add many of these standard features to a script: WSH can provide for input and output, it can read and write to the registry, and it can allow a script to accept command-line arguments. This ensures that any WSH-compatible language will be able to use these features, even if the language itself has no intrinsic support for them.

For example, suppose you need a script that can delete any folder from a computer; whenever you ran the script, you would pass the name of the folder to be deleted as a command-line argument:

deletefolder.vbs c:\scripts

You can use the FileSystemObject to delete folders, and you can write the script using the VBScript scripting language. But how do you handle command-line arguments? After all, neither the FileSystemObject nor VBScript have any knowledge of command-line arguments or how to use them.

Fortunately, you can use WSH to handle command-line arguments. For example, the following script actually uses three technologies:

  • Line 1 uses VBScript to instantiate the FileSystemObject (although this could also have been done using WSH).

  • Line 2 uses WSH to read the value of the command-line argument and assign it to a variable.

  • Line 3 uses the FileSystemObject to delete the specified folder.

Set objFSO = Wscript.CreateObject("Scripting.FileSystemObject")
strFolder = Wscript.Arguments.Item(0)
objFSO.DeleteFolder(strFolder)

This same script can be easily rewritten in Jscript, PythonScript or any other WSH-compatible scripting language. Do these languages support the use of command-line arguments? It does not matter; because they are WSH-compatible, you can use WSH to provide this capability.

The ability to run command-line tools

Obviously, WSH is not required to run command-line tools; command-line tools can be run as stand-alone programs or can be called from batch files. However, WSH is extremely useful if you want to add "intelligence" to these tools or batch files. For example, suppose you want to map a drive only if a user logs on from the fabrikam domain. If the user is from the fabrikam domain, you want to use the net use command to map drive X to \\atl-fs-01\public. If the user is not from the fabrikam domain, you do not want the script to do anything.

Can this be done from within a batch file? Yes, although the solution is not particularly straightforward. (You need to figure out how to get the domain name, how to pipe that name into the script, and how to use the shell language to take action based on the value of that name.) By contrast, this simple six-line script will accomplish the same task:

Set objNetwork = Wscript.CreateObject("Wscript.Network")
Set objShell = WScript.CreateObject("WScript.Shell")
strDomain = objNetwork.DomainName
If strDomain = "fabrikam" Then
    objShell.Run "net use x: \\atl-fs-01"
End If

In other words, not only can you run command-line tools from within your WSH scripts, but you can also augment those tools with capabilities that would be very difficult to replicate in a batch file.

WSH vs. Cmd.exe

At this point, it might be useful to briefly compare WSH and Cmd.exe, the command-line interpreter found in Windows. Both are scripting environments: WSH allows you to run WSH scripts; Cmd.exe allows you to run batch files (sometimes referred to as shell scripts). Both WSH and Cmd.exe require interaction with scripting languages and scripting tools: It is difficult to write useful scripts with nothing more than WSH, and it is difficult to write useful batch files with nothing more than the shell language.

This is where the differences between the two runtimes become more apparent. WSH provides access to a large number of sophisticated scripting languages; Cmd.exe limits you largely to the simplistic syntax of the batch file language. The only tools available to Cmd.exe are command-line utilities; WSH not only offers access to these same utilities but provides access to Automation objects as well. The scripting tools available to Cmd.exe represent a very small subset of the tools available to WSH. These differences make WSH a superior scripting environment.

Does this mean that you should throw away all your command-line tools and batch files and switch exclusively to WSH? Of course not if you have a solution that works, there is no reason to get rid of it. But for problems that batch files and command-line tools cannot solve, WSH, with its access to the myriad capabilities of VBScript, JScript, WMI, ADSI, and other Automation objects, might provide the solution you have been looking for.

A Note About WSH Versions

The sample scripts in this chapter were authored and tested with WSH version 5.6. Some of the WSH functionality described is available only under WSH version 5.6 or later. Therefore, you should determine which version of WSH you currently have installed on your computer; if it is earlier than version 5.6, you should upgrade it before proceeding with the chapter.

Note

  • Of course, the added functionality found in WSH 5.6 makes it a very worthwhile upgrade regardless of whether you intend to test the scripts found in this chapter.

To display the version of WSH installed on a computer, type cscript at the command prompt and then press ENTER. If you have WSH 5.6 installed, you should see output similar to this:

C:\WINDOWS>cscript
Microsoft (R) Windows Script Host Version 5.6
Copyright (C) Microsoft Corporation 1996-2000. All rights reserved.

You can also retrieve this information using the following script:

Wscript.Echo Wscript.Version

For information about downloading WSH version 5.6, go to the Windows Script Technologies link on the Web Resources page at https://www.microsoft.com/windows/reskits/webresources.