WSH, 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:

1. The file should begin with the <?XML version="1.0"?> element to indicate that the file is in XML format.
2. Elements are case sensitive and are enclosed in angle brackets.
3. The opening tag for an element is specified as <elementname>, and the closing tag uses a forward slash after the opening angle bracket and before the element name (e.g., </ elementname>).
4. Elements can have one or more attributes expressed in the form attribute="value". The attribute's value must be enclosed in double quotes. For example, <elementname attribute1= "value1" attribute2="value2">.
5. If an element doesn't have a closing tag, you must use a forward slash before the closing angle bracket in the opening tag; for example, < elementname attribute="value"/>.
6. Elements can include other elements as long as the tags don't overlap (i.e., the inner element must have an opening and closing tag before the outer element's closing tag).
7. You can create a comment element by inserting text between the opening <!— tag and the closing —> tag.

When you use the <?XML version="1.0"?> 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 &lt;, &gt;, and &amp, 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 <![CDATA\[ and ]]> markers.

Listing 1 shows the minimum required XML elements for a .wsf script. There must be at least one <job> element. The <script> element contains the VBScript or JScript code. The language attribute of the <script> element tells WSH which language engine it should use to execute the code. The code is placed in between the special <![CDATA\[ and ]]> markers to prevent any problems with the XML parser.

Including Standalone Code
Unlike standalone scripts, .wsf scripts let you easily include VBScript or JScript code from another file. Listing 2 shows a .wsf script that calls the Square function that's defined in the MathFunctions.vbs file. There are two important items to note about this example. First, the language attribute in the <script> element tells WSH the language engine it should use to process both the included file (in this case, MathFunctions.vbs) and the code listed between the <script> and </script> 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 <runtime> element inside a .wsf file's <job> element and enclose a set of elements in the <runtime> 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 <description> element. The <description> 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 <description> and </description> tags. Everything inside the < description> and </description> tags is included, including new lines, tabs, and spaces.

The <unnamed> element. The <unnamed> 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 <unnamed> 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.