Using COM Objects
Microsoft® Windows® 2000 Scripting Guide
If you have a question about practically anything sports, history, science, gardening it is likely that you can find the answer at the public library. However, this does not mean that you can walk into the library, pick out a book at random, and expect to find the answer. Instead, answers to specific questions are found in specific books, and you need to locate the correct book if you want to have your question answered.
The same thing applies to COM objects. There is likely to be a COM object that can be used to script most of your system administration needs. However, you cannot use just any COM object; COM objects have specific, oftentimes unique capabilities. By the same token, you cannot simply start using a COM object, just as you cannot start reading a book without first finding that book. (The one exception is the WScript object, which you can simply start using.) Instead, before a script can use a COM object, it must first bind to that object. The WScript object provides two methods for creating COM objects: CreateObject and GetObject.
Creating a New Instance of a COM Object
To create a new instance of a COM object, a script can call the WScript CreateObject method and pass it the Programmatic Identifier (ProgID) of the COM object by using the following syntax:
WScript.CreateObject(" ProgID")
To continue the analogy with the library, the ProgID is roughly equivalent to the call number assigned to a book. If you go to the library and give the librarian the call number, he or she can locate the book for you. Likewise, if you pass the scripting host a ProgID, the scripting host can look in the registry and locate the COM object you want to create. ProgIDs are unique to each COM object, just as call numbers are unique to each book.
How do you know the correct ProgID for a given COM object? Unfortunately, there is no simple answer to that question; your best course of action is to look at the documentation that accompanies the object. All ProgIDs are stored in the HKEY_CLASSES_ROOT portion of the registry, as shown in Figure 3.4. However, this listing is of only limited use because not all of these ProgIDs can be accessed using scripts.
Figure 3.4 ProgIDs in the Registry
.gif "sas_wsh_62s")
To be able to use a newly created object, the script needs to store a reference to the object in a variable by using the following syntax:
Set objVariable = WScript.CreateObject (" ProgID" )
After a reference to the object is stored in a variable, the script can call a method or access a property of the object by using dot notation. (Dot notation is discussed in the "VBScript Primer" chapter of this book.)
Scripts call methods by using the following syntax:
objVariable.MethodName
Scripts access properties by using the same syntax:
objVariable.PropertyName
The script in Listing 3.1 creates a new instance of the ADSI System Information object (using the ProgID ADSystemInfo), stores a reference to it in the objSysInfo variable, and then displays the Domain Name System (DNS) domain name for the logged-on user.
Listing 3.1 Using a COM Object
1 2 |
|
As shown in Figure 3.5, only two portions of the code statement must change when you create different COM objects: the ProgID, and the name of the reference variable (if your script must reference multiple COM objects).
Figure 3.5 Elements of a Statement That Creates a COM Object
.gif "sas_wsh_070c")
For example, the following lines of code bind to various COM objects. From line to line, the only item that changes is the ProgID:
Set objReference = Wscript.CreateObject("Word.Application")
Set objReference = Wscript.CreateObject("InternetExplorer.Application")
Set objReference = Wscript.CreateObject("Scripting.Dictionary")
Set objReference = Wscript.CreateObject("Wscript.Network")
Attaching to an Existing Instance of a COM Object
If the COM object you want to use is already running, you can use that existing object rather than create a new instance. The WScript GetObject method lets you reference and use a previously instantiated object instead of creating a new one.
When you write scripts that use WMI or ADSI, you will typically use the GetObject method; this is because both WMI and ADSI are always available. (For example, you can stop the WMI service, but if you run a script that uses WMI, the service will automatically restart.) Although there are exceptions, a typical WMI script might start like this:
Set objWMIService = Wscript.GetObject("winmgmts:")
When you are writing scripts that use the WSH objects, you will usually use the CreateObject method because the WSH objects are not usually preinstantiated.
Comparing VBScript CreateObject and GetObject Functions with WSH
The VBScript language also provides CreateObject and GetObject functions. The VBScript CreateObject function and the WScript CreateObject method both instantiate COM objects when they are called with a single parameter, the ProgID of the COM object to instantiate. For example, these two lines of code the first using the VBScript version of CreateObject and the second using the WSH version are functionally identical; both instantiate an instance of the FileSystemObject:
Set objFSO = CreateObject("Scripting.FileSystemObject")
Set objFSO = Wscript.CreateObject("Scripting.FileSystemObject")
Both versions of CreateObject can also accept a second parameter; however, each interprets this second parameter in a completely different way. Consider these two lines of code. The first line uses VBScript, and the second uses WSH:
Set objExcel = CreateObject("Excel.Application", "Parameter2")
Set objExcel = Wscript.CreateObject("Excel.Application", "Parameter2")
The VBScript CreateObject function interprets the second parameter as a remote computer name and tries to create the COM object on that remote computer; in this example, it tries to instantiate an instance of Microsoft Excel on a remote computer named Parameter2. The WScript CreateObject method interprets a second parameter as a subroutine prefix to be used in handling events from the object. The two GetObject functions are similarly related.
To simply create a COM object, you can use either the VBScript function or the WScript CreateObject method. After the object has been created, there are no differences in capabilities; all the methods and properties of the object available using Wscript CreateObject are also available using VBScript CreateObject. Furthermore, these properties and methods are all called in identical fashion.
On the other hand, if you want to use the remote object creation or event-handling capabilities, you need to choose the method or function that provides that additional functionality. For more information about the VBScript CreateObject and GetObject functions, see "VBScript Primer" in this book.