Windows Script Host—Intermediate

For the next 3 months, I'm going to show you how to create a progress bar dialog box that you can use with your scripts. The progress bar specifies both graphically and textually how a script's execution is proceeding.

One way to create this progress bar dialog box is to use Microsoft Visual Basic (VB) to create a COM object, then place the object inside a DLL. After you install and register that DLL on a machine, your scripts can call the DLL whenever you want a progress bar. Although effective, this solution requires that you write VB code and use a VB compiler.

A simpler solution is to use Windows Script Components (WSC—formerly called Scriptlets). WSC lets you create reusable COM objects in any scripting language that Windows Script Host (WSH) supports. These objects not only offer methods and properties but also support events.

This month, I show you what makes up WSC and how to begin building a progress bar dialog box. To create this progress bar dialog box, you need WSH 2.0, VBScript 5.0, and Microsoft Internet Explorer (IE) 4.0 or later. If you need any of these programs, go to http://www.microsoft.com/msdownload/vbscript/scripting.asp and download the Windows Script (WS) 5.5 set. You also need the Windows Script Component Wizard. WS 5.5 includes this wizard, but you can download it separately from the Microsoft Scripting Web site (http://msdn.microsoft.com/scripting/ default.htm?/scripting/scriptlets/default.htm). This site also contains the WSC language reference and supporting documentation.

What Makes Up WSC?
Simply stated, WSC consists of three components:

The script component runtime engine (scrobj.dll). This DLL helps dispatch COM requests to your scripts.

A set of interface handlers. Interface handlers are compiled COM components that implement specific COM interfaces. Microsoft built several interface handlers in the script component runtime engine, including the COM Automation, Active Server Pages (ASP), and IE 5.0 Dynamic HTML (DHTML) interface handlers. Other interface handlers are available as add-on components in DLLs or are embedded into specific applications. You'll be using the COM Automation interface handler for the progress bar dialog box.

Script component files. Script component (.wsc) files are .xml files that contain information about the type of COM component you want to create (i.e., the interface handler you want to use). Then, depending on the functionality the interface handler makes available, you write code in the .wsc file to implement those interfaces. For example, one of the most common types of COM components (and the one you'll be creating) is the Automation component, which is a component with properties, methods, and events that you can call from other applications. Microsoft built the low-level COM interfaces required to implement this functionality into an Automation interface handler. In your .wsc file, you define the properties, methods, and events you want to expose, and the Automation handler makes sure they're called correctly when the host application needs them. You use special XML elements to write these definitions.

What Are XML Elements?
In WSC, XML elements define the .wsc file's script component and its behavior. Because .xml files are similar to .html files, the XML elements are similar to HTML tags. A basic .wsc file might contain any number of the following common XML elements:

  • The <registration> element. If the host that will access the script component uses the Windows Registry to create an instance of that component (e.g., WSH), you need to include the <registration> element. This element lets you register your script component as an available COM component in the Registry. You don't need to include the <registration> element if the host doesn't directly use the Windows Registry when creating an instance of the script component (e.g., IE 5.0).

  • The <script> element. This element contains the code that implements the logic of the script component, depending on what type of COM component you're creating. For example, if you're creating a COM Automation component, you declare properties, methods, and events in a <public> element, then write the script to define them in one or more <script> elements.

  • The <public> element. This element contains declarations for properties, methods, and events that your script component exposes. The declarations point to variables or functions that you define in a separate <script> block. You use the <public> element to specify that a script component implements the COM Automation interface handler.

  • The <implements> element. This element specifies the COM interface handler for the script component, which determines what type of COM component the script component will be. Because the <public> element specifies that a script component implements the COM Automation interface handler, you don't need to use an <implements> element for the Automation handler.

  • The <component> and <package> elements. The <component> element contains one entire script component definition. Multiple <component> elements can appear in the same .wsc file, in which case a master <package> element contains the multiple <component> elements.

  • The <object> element. This element contains information about an object you're using in your script component, such as another COM component.

  • The <resource> element. This element contains values that you can't hard-code into your script component (e.g., dynamic data, strings that you need to translate).

  • The <reference> element. This element references a type library you want to use in your script component.

  • The <comment> element. This element contains text that the script component runtime engine ignores when it parses and executes the .wsc file.

The XML elements that you'll use to create the progress bar dialog box are <package>, <component>, <registration>, <public>, <implements>, and <script>. Now, let's move to the task at hand—building the script component. Let's look at the first stage in using WSC to build the progress bar dialog box.

How Do You Begin?
The first stage in building a script component is to identify its requirements and determine which objects, methods, properties, and events can meet those requirements. For example, suppose you want to create a small IE Web browser window with an HTML page that displays a progress bar. The first task is to consider how you want the progress bar dialog box to look and act. Then, you determine the methods, properties, and events this IE progress bar dialog box needs to meet those requirements.

Let's say you want a way to specify the dialog box's size and position because you don't want it to open at the default size that IE specifies. Checking the object model for the WebBrowser object in the Reference for Visual Basic Developers (http://msdn.microsoft.com/workshop/ c-frame.htm?/workshop/browser/webbrowser/reflist_vb.asp), you find that this object's Top, Left, Height, and Width properties let you set a dialog box's distance from the top of the screen, distance from the left of the screen, height, and width, respectively. The Reference for Visual Basic Developers is a handy guide when you're creating script components because it discusses all the supported properties, methods, and events of the WebBrowser and InternetExplorer objects. To navigate to this reference in the Microsoft Developer Network (MSDN) Library CD-ROM or DVD, go to Platform SDK, Web Services, Web Workshop, Reusing Browser Technology, Reusing the WebBrowser Control, Reference for VB.

With the dialog box's size and position requirements met, you can now identify the requirements for the progress bar and related elements. You want the dialog box to have a title and to textually and graphically show progress information. To display progress information textually, you need two string properties that you can change as the script progresses. To display progress information graphically, you need a property that lets you specify in a percentage how complete the script's execution is so that you can accurately draw the progress bar. To cancel the script's execution if a problem occurs, you need an event. Finally, you need a way to easily display or hide the dialog box on the screen.

No object currently meets all these requirements. However, you can build a custom WSC object called ProgressDialogBox with the methods and properties from the IE object model. Then, in a script, you can use ProgressDialogBox to take in the necessary parameters and pass those parameters to the appropriate methods and properties of the IE objects.

To meet the specified requirements, ProgressDialogBox needs two methods: Open and Close. The Open method needs to take in five parameters:

objBox.Open "title", w, x, y, z

where "title" is the dialog box's title, w is the dialog box's distance from the top of the screen, x is the dialog box's distance from the left of the screen, y is the dialog box's height, and z is the dialog box's width.

ProgressDialogBox needs four write-only properties (i.e., Line1, Line2, PercentageComplete, and Visible) and one event (i.e., Cancel). The Line1 and Line2 properties are the strings you use for the dialog box's textual progress information. The PercentageComplete property provides the percentage you use to draw the progress bar, and the Visible property lets you easily display or hide a dialog box. The Cancel event lets you cancel the script, if necessary. Table 1 summarizes these properties, methods, and events and provides examples of their usage.

Next Month
Next month, I'll show you how to create the ProgressDialogBox object. In the final month, I'll show you how to build up ProgressDialogBox object's functionality and use the object you've created.