An Introduction to Windows Script Components

Transcription

1 An Introduction to Windows Script Components Windows Script Components (WSC) provide with a simple and easy way to create COM components. You can use scripting languages such as JScript, VBScript, PERLScript, PScript and Python, which support ActiveX Scripting interface to create them. The WSC supports common types components for Automation and can be extended further by using add-ons such as DHTML behaviors. WSC is used to create COM components for tasks such as: Middle-tier business logic Database insertion and retrieval Addition of transaction processes to applications Adding interactive effects to a Web page using DHTML Behaviors Salient features of WSC: Small and efficient Easy to create, maintain and deploy Ability to create COM components Ability to access a broad range of system services

2 Elements of A WSC File WSC consists of: Scrobj.dll: Is an acronym for Script Component Run-Time, which helps to dispatch COM requests to scripts. In terms of COM terminology, Scrobj.dll functions as inproc server for script components. Interface Handlers: These are compiled components that implement specific COM interfaces. Typical interface handlers like COM Automation interface handler, ASP interface handler and a handler for DHTML Behaviors are already built into the Script component run-time and the rest are available as add-on components or embedded into specific applications. Script Component File: These are XML files that contain information about the type of COM component you wish to create and depending on the functionality that handler provides, you will provide a script in the script component to implement those interfaces. Example of Script Component file is.wsc The script component run-time environment serves as a starting point for the host applications. The complexities of COM, including the implementation of such COM-standard interfaces as IUnknown, are embedded in various interface handlers. Your script component contains only the script needed to implement the functionality of the COM component. For example, one of the most common types of COM components is an Automation component. The Automation Component has properties and methods, which can be called from other applications. The low-level COM interfaces needed to implement this functionality such as dispatching to the correct function when a method is called, are built into an Automation interface handler. In your script component file, you define the properties, methods, and events you want to expose, and the Automation handler makes sure that they are called correctly when the host application needs them.

3 Usage of Script Components in an Application A WSC can be used as any other COM component, by calling it from a host application such as Microsoft Visual Basic, C++, Microsoft Internet Explorer, or other applications. Note: Script components written for DHTML Behaviors are instantiated differently than traditional COM objects. There are a variety of options for creating an instance of the script component, depending on the host application, the type of script component being used and the location where the script component is deployed. The primary difference lies in, whether you create an instance of the script component locally (on the same computer as the application) or remotely (on another computer). If you create an instance of the script component and change the.wsc file while using that instance, your instance of the component is not updated. To update it, create a new instance of the script component. The properties and methods that you can use are defined by the <public> element and by scripts in the script component file. If you are working in an environment that supports statement completion, such as Visual Basic, you can see a script component's properties and methods if you generate and use a type library. If your attempt to create an instance of the script component fails, a likely cause is a syntax or run-time error in the script component file. While developing the script component file, set error checking options in the <?component?> <leteleqscriptlet.asp> processing instruction as described in Checking For Errors in Script Component Files.

4 Installing Script Components On Local Machines You may need to use the developed components on a local machine for testing applications or other purposes. You can register the script component as the applications own component. To use the component, create an object instance using a function like the CreateObject. As in the example given below, you can create an instance of the script component that was registered with the program ID libmain.read. Here the statement is in Visual Basic, Dim ocomponent as object Private Sub Command1_Click() Set ocomponent=new Component.mycomponent End Sub Note: If the application is Visual Basic as in the example above, to handle events triggered by the script component, you must bind the object early with a Dim statement and attach it to an event. While implementing the component for a Web Application, you have to use the <OBJECT> tag to create an instance of the script component. You must know the class ID of the script component and include it in the <OBJECT> tag, as in the following example: <OBJECT ID="oComponent" CLASSID="clsid:307c ba-11d2-a428-00c04f8ec80b"> </OBJECT>

5 To register a script component, which has not been registered with an application on the local computer, you can use the script component moniker to create an instance of it and register Scrobj.dll on the local computer. The moniker is supported in functions such as GetObject. Note: The GetObject function is not supported for script components in Internet Explorer for security reasons. The example given below demonstrates how you can call the Visual Basic GetObject function to create an instance of an unregistered script component: Set ocomponent = GetObject("script:c:\COM\MyComponent.wsc") If the.wsc file referenced by the moniker contains more than one script component, specify the script component to instantiate by adding its name to the file name with a hash mark (#) as a delimiter. The example below demonstrates how to create an instance of the script component whose ID is "calcsum" contained in the file Calc.wsc: Set ocomponent = GetObject("script:c:\COM\Calc.wsc#calcSum") Using a URL moniker, you can create an instance of a script component that resides on another computer, such as a Web server. Use a complete URL (with HTTP protocol) as the location for the script component, as in the example: Set ocomponent = GetObject("script:

6 Creating Remote Instances of a Script Component If the remote attribute of a script component's <registration> element has been set to "true," the script component can be instantiated remotely from another computer using Distributed COM (DCOM) provided both computers have basic DCOM installed. A computer is correctly configured with DCOM if it is running any of: Windows NT 4.0, Windows 98, Windows Millennium Edition, Windows 2000, or Windows XP Windows 95 running Internet Explorer 4.0 Windows 95 with the OEM Service Release 2 (OSR2) or later. For details, see the Windows 95 OSR2 page on the Microsoft Web site. Windows 95 with DCOM for Windows 95, version 1.2. For details, see the DCOM for Windows 95 page on the Microsoft Web site. The script component must be deployed as follows: On the local computer, the script component (.wsc file) or the script component run-time (Scrobj.dll) are not rquired at the time of instantiating the script component but a reference to the remote script component in the local Windows registry for DCOM is required. On the remote computer, you require the script component and the script component runtime and both must be registered. When an instance of a remote script component is created, it works within the application as if it were a local object; you call its methods and get and set its properties normally. But, the remote script component's script runs on the remote machine and has access to that machine's resources (within any limitations imposed by security, and so forth). Communication between the host application on the local machine and the script component on the remote machine is handled automatically and invisibly by DCOM. To create a remote instance of a script component, call the CreateObject method and pass the name of the remote computer as a parameter.

7 Note: The use CreateObject for instantiating remote script components, Visual Basic 6.0 or later or VBScript 5.0 or later is required. Example that shows how Visual Basic s CreateObject is used for instantiating remote server myserver. Set news = CreateObject("Component.MyComponent", "myserver") Note: There can be a slight delay when you first instantiate a remote script component while DCOM establishes communication between the computers. Handling Script Component Events in the Host Application Most of the host applications can receive Windows Script Component events as they do any other events but some require some setup before they can receive script component events. Note: If you are creating a Behavior script component, events are exposed using the DHTML object model. In Visual Basic, for example, you must use early (compile-time) binding to the component in order to receive events. Early binding requires a type library, so you must have generated a type library for the script component. In addition, when you declare the object variable for the component, you must specify the WithEvents keyword. (The class name used in the Dim statement is the ID that you assigned in the script component's <component> <letelescriptlet.asp> element.) An example in Visual Basic look like this: Dim WithEvents Scriptlet1 as MyScriptlet Set Scriptlet1 = CreateObject("MyScriptlet") Sub Scriptlet1_namechanged MsgBox("Value of name property changed") End Sub

8 Creating Registration Information Registration information places information about the COM component in a public location. For instance, in Windows, the registration information is stored in the Windows registry. By reading the registration information, applications can find and load the COM component. Note: Creation of registration information is not a must in every case. For example, a script component that implements DHTML Behaviors interface handler in IE 5.0 does not require registration, since IE registers the behaviors as they are detected on the page. You can create an instance of a script component without registering it, if the host application supports monikers. If the host application requires it, you can register a WSC as a COM component using a program such as Regsvr32.exe. A WSC can be registered as a COM component by using Regsvr32.exe. When you specify registration, the most important information is: A program ID (prog ID), the name used in the host application when creating an instance of the script component. For example, if the script component's program ID is Component.MyComponent, you can create an instance of it in Microsoft Visual Basic using the statement as shown below: Set Component = CreateObject("Component.MyComponent") A class ID is a GUID (globally unique ID) uniquely identifies a script component. A GUID can be generated using Uuidgen.exe. Registration information also includes a description and a version number.

9 Note: If a script component is created by using the Script Component Wizard, the wizard automatically creates a program ID and class ID for you. The registration program can create a class ID for a script component when it is registered but it is highly recommended that you provide a class ID for the script component yourself, to ensure that your script component has the same class ID on all computers on which it is registered. Creating Registration Information For A Script Component Create an <registration> <leteleregistration.asp> element that includes at least a program ID, and optionally, a class ID, description, and version, as shown in the example below: Note: <registration description="my Test Component" progid="component.testscript" version="1" classid="{2154c d1-a3ac-0aa0044eb5f}"/> The registration attributes can appear in any order in the <registration> element. Running Script During Registration The script component <registration> element allows inclusion of script, which will be executed when the script component is registered and unregistered. How To Run A Script During Registration And De-registration Include an <script> <letelescript.asp> element in the <registration> <leteleregistration.asp> element. To run script during registration, write

10 a register( ) function and to run a script during De-registration, write a de-register( ) function. An instance that demonstrates the procedure for posting a message when the script component is registered/unregistered: <registration description="my Test Component" progid="component.testscript" version="1" classid="{2154c d1-a3ac-0aa0044eb5f}"> <script language="vbscript"> <![CDATA[ Function register() MsgBox "Component 'My Test Component' registered." End Function Function unregister() MsgBox "Component 'My Test Component' unregistered." End Function ]]> </script> </registration> Note: Script written in the <script> tag can be made opaque by using CDATA. Registering For A Remote Access A script component can be instantiated remotely, if it is deployed in a distributed environment. For example, you may be creating a script component designed to run on a server, but called from the client s machine. This is possible if the client and server machines are properly configured with DCOM, which provides the mechanism for passing object pointers between the client and server.

11 Registering A Script Component For Remote Access Include the remote attribute in the <registration> <leteleregistration.asp> element, as shown in the below example: <registration description="my Test Component" progid="component.testscript" version="1" classid="{2154c d1-a3ac-0aa0044eb5f}" remotable=true/> Registering a Script Component To register a WSC, the script component run-time Scrobj.dll should be registered on your computer. When the script component is installed from the Microsoft Scripting Technologies Web site, Scrobj.dll is automatically loaded and registered on your computer. Note: Registration is not required if you are creating a script component to be called via DHTML Behaviors, because Microsoft IE 5.0 can use this type of script component without prior registration. A script component can be registered on a local computer via various methods. To register a Script Component in Windows Explorer: Right-click the script component (.wsc) file and then choose Register. Or Use the new version of Regsvr32.exe that ships with the script component package and use this command: regsvr32 URL/component_name.wsc For example, to register a script component called MyComponent.wsc, use syntax such as this:

12 -or regsvr32 file:\\myserver\mycomponent.wsc If you do not have the version of Regsvr32.exe that ships with the script component package, use the existing version and register the script component run-time DLL using syntax such as the following: regsvr32 scrobj.dll /n /i:url/component_name.ext For example, to register a script component called MyComponent.wsc, use syntax such as this: regsvr32 scrobj.dll /n /i: Registering a Script Component for Remote Instantiation To create a remote instance of a script component, the script component must be registered on the remote computer where it resides. You must also register it on each local computer from which you intend to instantiate the script component, so that DCOM can have a starting point in the registry to find and instantiate the remote script component. Determine the program ID and class ID of the script component to be instantiated remotely. Note: The script component must have the same class ID on both the local and remote computers, so you must provide a class ID in the script component's <registration> <leteleregistration.asp> element. On each local computer, create the following registry entry: HKEY_CLASSES_ROOT\componentProgID where componentprogid is the program ID of the script component to instantiate. Under the new entry, create the CLSID key and set its value to the class ID of the script component, enclosing the class ID in brackets.

13 Tip: An easy way to create the proper registry information is to register the script component on the server where it will be instantiated. Then using Regedit.exe, locate the HKEY_CLASSES_ROOT\componentProgID entry. From the Registry menu, choose Export Registry File, which creates a.reg file. This file can be distributed to local computers, and users can simply run the file to create the appropriate registry entries. Un-Registering a Component To remove a Script Component from the registry you can use either of the 2 methods stated below: Locate the registry folder and Right-click the script component file name in Windows Explorer, and then choose Un-register. Run Regsvr32.exe with the -u flag. Creating a Script Component Type Library You can generate a type library for your Windows Script Component containing information about its interfaces and members. In some host applications (such as Visual Basic), Type Libraries are necessary to enable events for the script component while in other host applications Type Libraries are optional. However, even if a type library is not required, generating one can make working with a script component easier and less error-prone in the host application. For example, if you are using Visual Basic as your host application, use the References dialog box to select a script component's type library. This allows you to bind events to the script component and make them visible in Visual Basic. In addition, when you are writing Visual Basic code that references the script component, Visual Basic uses the type library information in statement completion and in the Object Browser so you can easily see and use properties, methods and events that the script component exposes.

14 Note: For information about using a type library in the host application, refer to the application's documentation. Creating A Script Component Type Library In Windows Explorer, right-click the script component.wsc file, and then choose Generate Type Library. A.tlb file is generated for the script component with the same name as the script component file, written to the folder where the.wsc file is and registered in the Windows registry. For more precise control over generating type libraries, you can generate the type library dynamically from script inside the script component file, or you can use a command-line interface. Generating Type Libraries Dynamically The script component run-time includes an Automation interface implemented by the Component.TypeLib object. You can use this object in script to generate a type library from within the script component file. This is particularly useful for creating a type library automatically when the script component is registered. Dynamic Creation Of A Script Component Type Library In the script, inside the script component file, create an instance of the Component.TypeLib object by using syntax as shown: set otl = CreateObject("Scriptlet.TypeLib")

15 Set the following properties of the Component.TypeLib object. Property/Method AddURL(Method) Path(Property) Doc(Property) GUID(Property) Name(Property) MajorVersion(Property) MinorVersion(Property) Description Adds the URL of the script component file from which to generate the type library. You can call this method property multiple times to include multiple script components in the type library. The path and file where the type library will be written. The default path is the current directory and the default name is the name of the script component file with a.tlb extension. If the object is unable to create the specified library, it defaults to creating a type library called component.tlb. A string containing any information that is stored in the registry with the type library information. A GUID for the type library. (This is not the GUID for the script component.) If you do not provi de one, the TypeLib object will create one, but then the type library will have a different GUID on each machine. The GUID must be exactly in this format, where x represents a hex value: {xxxxxxxx-xxxxxxxx-xxxx-xxxxxxxxxxxx} The internal name for the type library. This name is displayed in some applications, such as the Visual Basic Object Browser. An integer value you assign. An integer value you assign. Call the type library object's Write method to create the.tlb file, then register it. If you want to create an additional type library, call the TypeLib object's Reset method to clear the list of script component files in the AddURL property, reset the URLs and any other properties you want, and then call the Write method again. For example, the following script in a <registration> element creates a type library dynamically.

16 Note: A CDATA section is required to make the script in the <script> element opaque. For details, see Script Component Files and XML Conformance. <letxml.asp>. <registration description="my Test Component" progid="component.testscript" version="1" classid="{2154c d1-a3ac-0aa0044eb5f}"> <script language="vbscript"> <![CDATA[ Function Register() Set otl = CreateObject("Scriptlet.TypeLib") otl.addurl "d:\components\mycomponent.wsc" ' Script component URL. otl.addurl "d:\components\yourcomponent.wsc" otl.path = "d:\components\mycomponent.tlb" '.tlb path. otl.doc = "Sample component typelib" ' Documentation string. otl.guid = "{a1e1e3e0-a252-11d1-9fa1-00a0c90fffc0}" otl.name = "MyComponentTLib" ' Internal name for tlb. otl.majorversion = 1 otl.minorversion = 0 otl.write ' Write tlib to disk. otl.reset ' Clear list of URLs in AddURL/. End Function ]]> </script> </registration>

17 Command-line Interface If you are comfortable using the Command Prompt window, you can call the Rundll32.exe program to create type libraries. Creating A Type Library From The Command Prompt Call Rundll32.exe using this syntax: rundll32.exe path\scrobj.dll,typelib options Where: Path: The path where Scrobj.dll is located on your computer. Options: A set of flags and values you can use to specify type library information in the form -flag:value. You can specify the options in any order. The following flags are supported, with values as described under the previous section, to create a script component type library dynamically. -name:name -file:path -doc:\"doc\" -guid:guid -major:majorversion -minor:minorversion -URL:AddURL

18 For example, the following command demonstrates the creation of a Type Library called dcont.tlb from the script component MyCont.wsc (the command is wrapped for clarity): rundll32.exe c:\winnt\system32\scrobj.dll,typelib -name:dconttlib -file:d:\components\dcont.tlb -doc:\"sample component typelib\" -guid:{a1e1e3e0-a252-11d1-9fa1-00a0c90fffc0} -major:1 - minor:0 -URL:d:\components\MyCont.wsc Component Referencing Your WSC can include references to external components that you need to create the script component, such as: Additional COM objects Type libraries Resources, such as numbers and text, that you do not want to hardcode into your script component's scripts. Referencing Additional COM Components In your script component, it might be necessary to create instances of other COM components as needed. You can do so in two ways: In script: Create instances of other objects directly in your script. For example, you can use the CreateObject function in Microsoft Visual Basic Scripting Edition (VBScript) or the new ActiveXObject Object in JScript. Using an OBJECT element: Use an <object> element similar to the <OBJECT> tag you use in HTML pages. Using an <object> element makes objects globally available to any script and allows scripting tools to provide statement completion. It also provides a convenient way to summarize and document the objects you use in your script component. Note: Although <object> elements in script components are similar to <OBJECT> tags in HTML pages, the list of attributes for an <object> element in a script component is shorter, because script components do not present a user interface.

19 Referencing An External Type Library Many components that you might work with support type libraries, which provide a complete listing of the component's classes and their members. By referencing the component's type libraries, you can use constants defined in the type library. To include a reference to a Type Library Include a <reference> <letelereference.asp> element in your script component that specifies the location and name of the type library to include. For example: <reference object="adodb.connection.2.0"/> Referencing Resources Resource elements can include information that might change between versions, strings that might be translated, and other values. To reference Resources in the script component, but outside of the <public> and <script> elements (and <implements> element, if any), create one <resource> <leteleresource.asp> element for each resource you want to define, giving each element a unique ID. The following example shows two <resource> elements: Note: A CDATA section is required to make the contents of the <resource> element opaque to the parser. For details, see Script Component Files and XML Conformance. <letxml.asp>. <component id="myscriptlet"> <public> <method name="random" internalname="getrandomnumber"/> </public> <resource id="errnonnumeric"><![cdata[non-numeric value passed]]> </resource> <resource id="erroutofrange"><![cdata[passed value

20 is out of range ]]> </resource> In your script, include the resource text or number by calling the getresource <letfctgetresource.asp> function, as shown in the following example. Note: A CDATA section is required to make the script in the <script> element opaque to the parser. For details, see Script Component Files and XML Conformance <letxml.asp>. <script language="vbscript"> <![CDATA[ Function getrandomnumber(upperbound) If IsNumeric(upperBound) Then getrandomnumber = Cint(upperBound * Rnd + 1) Else getrandomnumber=getresource("errnonnumeric") End If End Function ]]> </script> Error Options You can set the error option by specifying the error option as an attribute of the XML <?component?> processing instruction. How to Specify Error Checking? Include the <?component?> <leteleqscriptlet.asp> processing instruction at the top of the script component file but below the optional <?XML?> <letelexml.asp> declaration, with one or more of the following attributes:

21 Error: Set this to true for displaying detailed error messages for syntax or run-time errors in the script component. Debug: Set this to true to enable debugging. And, if set false, the script debugger cannot be launced for a script component. For example, to enable all the three error reporting options: <?component error="true" debug="true"?> Tip: Turn error reporting off before deploying the script component to a production environment.