Create reusable code by writing your own COM objects in script
A Windows Script Component (WSC), formerly known as a server scriptlet, is a COM component (also known as an ActiveX object or an OLE automation object) implemented in a script language. A WSC file is an XML-format text file that uses the .wsc file extension. One of the main advantages of WSCs is code reuse: The object implemented by the WSC is available for use in any Windows Script Host (WSH) script. Let's look at the elements of WSC files and a real-life example of how to use them.
Understanding COM Components
To understand the WSC file format, it helps to have a basic understanding of COM components. COM is one of the core technologies that make WSH so useful. A WSH script can use a host of COM components to access functionality that the script language itself doesn't provide. For example, VBScript doesn't by itself provide any way to access the file system, but you can use the Scripting.FileSystemObject COM component in a VBScript script to open files. To get real administrative work done, WSH scripts rely heavily on COM components.
You can create your own COM components entirely in script code. Coding your own components provides a convenient way to create standalone objects that can be freely used by multiple scripts—or even by other programming languages that support COM components, such as Visual Basic (VB).
Understanding WSC Files
As I mentioned earlier, a WSC file is an XML-format text file that provides a set of elements and attributes that define an object's interface (e.g., the properties and methods available to calling scripts) as well as its implementation in a script language. For those who aren't familiar with XML, I provide a short list of its syntax rules in "WSH, Part 2: .wsf Files," February 2006, InstantDoc ID 48692.
WSC files have their own list of XML elements:
- The <component> element. encloses the entire definition of a script component. All of the elements that follow must be between the <component> and </ component> tags.
- The <?component?> element allows for more extensive error checking in the component. It uses two attributes: error and debug. Use error="true" to display more detailed error messages, and use debug="true" to be able to step through the component's code in the script debugger.
- The <registration> element provides the information needed to register the component as a COM component on the system. It has four required attributes, as shown in Table 1. You can generate a valid globally unique identifier (GUID) by using the Windows Script Component Wizard (see the Additional Resources box) or the guidgen.exe tool in the platform software development kit (SDK). When you register or unregister the component (a process I'll describe shortly), the WSC runtime uses the information in the <registration> element to update the registry.
- The <public> element specifies the component's interface (e.g., the properties and methods it makes available). The <property> and <method> elements are both enclosed within the <public> element.
- The <property="propertyname"> element declares a property for the component. For a simple read/write property, the < property> element references a global variable in the script code. The global variable's name should match the property's name unless you include the internalname attribute to reference a different variable. The <property> element can also use the <put/> and <get/> elements (they don't have closing tags) when you want to call code when setting and/or retrieving the property's value or when you want to create a write-only or read-only property. To create a write-only property, the <property> element should include only a <put/> element. The script code should define a function named put_propertyname, where propertyname is the name of the property. Conversely, a read-only property should include only a <get/> element, and the script should have a function called get_propertyname. You can use different property function names by adding the internalname attribute to the <put/> or <get/> element.
- The <method="methodname"> element declares a method for the component. The method name should match the name of a function in the script code. (As with the <property> element, if you want to use a different function name, use the internalname attribute.) If needed, use one or more <parameter="parametername"/> elements to declare parameters for the function.
- The <script language= "language"> element encloses the script code that implements the component. The language attribute tells the WSC runtime which language engine it should use to process the script. To avoid problems with the XML parser when using the <?XML version="1.0"?> element at the top of the file, place the script code between the XML <!\[CDATA\[ and \]\]> markers.
Listing 1 shows the sample script component Sample.wsc. It provides a single write-only property, Number, and one method, Multiply. The Number property is write-only because it has only a <put/> element. When setting this property, the script component runtime executes the put_ Number function, with the new property-value as the parameter to the function. The Multiply method multiplies the Number variable by the parameter passed to the function and returns the result.
Registering and Unregistering a Component
To make a component available to scripts or programs, you have to register it on the system to add the appropriate data to the registry. The easiest way to register a script component is to right-click the WSC file in Windows Explorer and choose Register. You can also type the following command at a command prompt:
regsvr32 /i:<wscfile> %SystemRoot%\system32\scrobj.dll
To unregister a component (i.e., remove its registration data from the registry), right-click the WSC file in Windows Explorer and choose Unregister, or type the following command at the command prompt:
regsvr32 /u /n /i:<wscfile> %SystemRoot%\system32\scrobj.dll
To silently register or unregister a script component file from the command line, add the /s option after the Regsvr32 command. If the WSC file's path or filename contains spaces, you must enclose it in double quotes. You must be a member of the Administrators group to register or unregister a script component.
A Real-World Example
"WSH, Part 2: .wsf Files" presents a WSF script that reports the members of a group. To continue this theme, I decided to present a script component that provides the same functionality. The Penton.GetMembers component provides two write-only properties, GroupName and Domain-Name, and one method, Members. The Members method returns a sorted array containing the members of the group. Listing 2 shows the VBScript implementation of the GroupName and DomainName properties and the Members method. Listing 2 is only an excerpt from the Penton.GetMembers component. You can download the entire component from the Windows Scripting Solutions Web site. Go to http://www.windowsitpro.com/windowsscripting, enter 49092 in the InstantDoc ID text box, then click the 49092.zip hotlink.
At callout A in Listing 2, note how the Members method calls the SortVBArray JScript function, which I created earlier in the component. This function returns a sorted copy of the specified VB safe array. (A safe array, also known as a VB array, is the array type used by VBScript.)
To use the Penton.GetMembers component in a script, create an object instance of it. Next, set the GroupName property to the name of the group (it defaults to Domain Admins). If the group exists in a domain other than the current logon domain, set the DomainName property as well. Finally, call the Members method to retrieve the array containing the members of the group. UseGetMembers.vbs, shown in Listing 3, uses the object to list the members of the Domain Users group in the current domain. (Be sure to execute this script with the CScript host because it uses WScript.Echo to output each member.) Note that the GetMembers.wsc file must be registered on the system before the script in Listing 3 will work.
Creating Your Own Components
This article provides only a brief overview of script components and doesn't cover some of their more advanced features. My goal was to explain the basics and why they might be useful in your own scripting tasks. Use the examples in this article to start creating your own components.
Windows Script Component Wizard The Windows Script Component Wizard generates a prototype WSC file based on your inputs to the wizard. Even if you don't click the wizard's Finish button, you can still copy the GUID it creates and paste it into your component. http://www.microsoft.com/downloads/details.aspx?familyid=408024ed-faad-4835-8e68-773ccc951a6b
Windows Script 5.6 Documentation This download provides documentation for VBScript, JScript, WSH, the scripting runtime, and script components in one searchable Help file. http://www.microsoft.com/downloads/details.aspx?familyid=01592c48-207d-4be1-8a76-1c4099d7bbb9