WSH, Part 2: .wsf FilesWSH, Part 2: .wsf Files

As I described in "WSH, Part 1: File Types," January 2006, InstantDoc ID 48498, Windows Script Host (WSH) is a COMbased scripting host that can execute scripts in Windows. It natively supports both JScript and VBScript, but other languages are also available if you install them separately.

WSH can execute both standalone (e.g., language-specific) scripts and Windows Script file (.wsf) scripts. The latter scripts are XML-formatted text files that can contain code in more than one scripting language. Although they're slightly more complex to write, .wsf scripts provide the script author some other useful features that are tedious or difficult to implement by using standalone scripts.

The .wsf XML File Format
The XML format that .wsf scripts use looks similar to HTML. XML uses markup tags enclosed in angle brackets (< >), called elements, that describe the data in the file. The full list of XML elements used in .wsf files is provided at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/wsorixmlelements.asp. A brief overview of XML syntax is as follows:

When you use the element, the angle brackets (< and >) and ampersand (&) characters have special meanings to the XML parser when they occur in element content and must be replaced with the character sequences <, >, and &, respectively.

Unfortunately, these characters tend to occur frequently in VBScript and JScript code. To avoid having to make the replacements while still avoiding XML parsing problems, you can enclose all VBScript and JScript code between the markers.

Listing 1 shows the minimum required XML elements for a .wsf script. There must be at least one element. The tags. Second, you don't have to include the full path to the included file. WSH assumes it's stored in the same directory as the script unless you specify otherwise.

Note also that the referenced file should contain only code in the desired language, not XML elements. For example, you can't include code from another .wsf file.

Self-Documenting Scripts
You can include the element inside a .wsf file's element and enclose a set of elements in the element to make a script self-documenting. Then, when you specify a /? argument on the script's command line or call the WScript .Arguments object's ShowUsage method, WSH will display a short usage message based on the < runtime> element's contents. The < runtime> element can include the following elements:

The element. The element should contain a short description of the script. If you execute the script with the /? command-line argument or call the WScript.Arguments object's Show-Usage method, WSH will automatically display the text in between the and tags. Everything inside the < description> and tags is included, including new lines, tabs, and spaces.

The element. The element describes the script's unnamed arguments (i.e., arguments that don't start with the / character). This element doesn't have a closing tag and has two mandatory attributes: the name attribute (which specifies the argument's name) and the helpstring attribute (which describes the argument). You can set a third attribute, the required attribute, to "true" or "false" to determine whether the argument's name will be enclosed in square brackets ([ ]) in the usage message. (The default is "false".)

The element can also include the many attribute, which must be a boolean ("true" or "false") value. If "true", the usage message will indicate that the argument can be specified more than once by using a number after the argument's name and an ellipsis (...). If you specify many="true", you can also use the required attribute to specify the number of arguments required.

The element. The element describes a script's named arguments (i.e., command-line arguments that start with a / character). This element doesn't have a closing tag and requires the name and helpstring attributes to provide a name and description for the named argument. If you include required= "true", the argument won't appear in square brackets in the usage message.

The type attribute is optional and indicates the argument's data type; it can be "string", "boolean", or "simple" (The default is "simple".) The type attribute affects the display of the usage message: If you use type="string", the argument will be appended with a colon (:) and the string value to indicate that a value is required. If you use type="boolean", the argument is appended with the string [+|-] to indicate that the user should type a plus (+) or minus (-) character after the argument name. If you use type="simple" (or omit the type attribute), the argument is displayed as is.

It's important to note that the and elements merely define what appears in the usage message when you run the script with the /? argument or when the script executes the WScript. Arguments object's ShowUsage method. These elements don't validate your script's command-line arguments; they simply document what the arguments should be.

The element. The < example> element is optional; it lets you provide a sample usage for the script. It will be displayed after the description and command-line arguments. As with the element, everything between the and tags is included, including new lines, spaces, and tabs.

The element. If you don't like the default usage message, you can use the element to override it. You can still use the other elements to benefit anyone reading the script. As with the and elements, everything between the and tags is included, including spaces, tabs, and new lines.

Listing 3 shows a sample script that uses the , , and elements, and Figure 1 shows the usage message when you execute the script with the WScript host. Note that the elements don't use the required="true" attribute, so they appear in square brackets to indicate that they're optional.

Multi-Language Scripts
Another strength of .wsf scripts is their ability to execute code in multiple languages: That is, a element can contain more than one