[This is preliminary documentation and subject to change]

# Using Components and Objects

COM components are the key to building powerful, real-world Web applications. Components provide functionality that you use in your scripts to perform specialized tasks, such as executing financial transactions or validating data. ASP also provides a set of base components that you can use to greatly enhance your scripts.

## About Components

A COM component is a reusable, programmatic building block that contains code for performing a task or set of tasks. Components can be combined with other components (even across networks) to create a Web application. COM components execute common tasks so that you do not have to create your own code to perform these tasks. For example, you can use a stock ticker component to display the latest stock quotes on a Web page. However, it would be difficult to create a script that provides the same functionality. Also, the script would not be as reusable as a component.

If you are new to scripting, you can write scripts that use components without knowing anything about how the component works. ASP comes with base components that you can use immediately. For example, you can use the ActiveX Data Objects (ADO) components to add database connectivity to your Web pages. Additional components can also be obtained from third-party developers.

If you are a Web application developer, components are the best way to encapsulate your business logic into reusable, secure modules. For example, you could use a component to verify credit card numbers by calling the component from a script that processes sales orders. Because the verification is isolated from the order process, you can update the component when the credit card verification process changes, without changing your order process. Also, since COM components are reusable, you could reuse the component in other scripts and applications. Once you have installed a component on your Web server, you can call it from a ASP server-side script, an ISAPI extension, another component on the server, or a program written in another COM-compatible language.

You can create components in any programming language that supports the Component Object Model (COM), such as C, C++, Java, Visual Basic, or numerous scripting languages. (If you are familiar with COM programming, COM components are also known as Automation servers.) To run on the Web server, your COM components cannot have any graphical user interface elements, such as the Visual Basic MsgBox function; graphical interface elements would only be viewable on the server, and not the browser.

## Creating an Instance of a Component's Object

A component is executable code contained in a dynamic-link library (.dll) or in an executable (.exe) file. Components provide one or more objects, self contained units of code which perform specific functions within the component. Each object has methods (programmed procedures) and properties (behavioral attributes). To use an object provided by a component, you create an instance of the object and assign the new instance to a variable name. Use the ASP Server.CreateObject method or the HTML <OBJECT> tag to create the object instance. Use your scripting language's variable assignment statement to give your object instance a name. When you create the object instance, you must provide its registered name (PROGID). For the base components provided with ASP, you can get the PROGID for the objects from the reference pages (see ASP Installable Components Reference).

For example, the Ad Rotator component randomly rotates through a series of graphical advertisements. The Ad Rotator component provides one object, called the Ad Rotator object, whose PROGID is "MSWC.AdRotator." To create an instance of the Ad Rotator object, use one of the following statements:

VBScript:

    <% Set MyAds = Server.CreateObject("MSWC.AdRotator") %>

JScript:

    <% var MyAds = Server.CreateObject("MSWC.AdRotator") %>

If you are already familiar with VBScript or JScript, note that you do not use the scripting language's function for creating a new object instance (CreateObject in VBScript or New in JScript). You must use the ASP Server.CreateObject method; otherwise, ASP cannot track your use of the object in your scripts.

You can also use the HTML <OBJECT> tag to create an object instance. You must supply the RUNAT attribute with a value of Server, and you must provide the ID attribute set to the variable name you will use in your scripts. You can identify the object by using either its registered name (PROGID) or its registered number (CLSID).The following example uses the registered name (PROGID) to create an instance of the Ad Rotator object:

    <OBJECT RUNAT=Server ID=MyAds PROG></OBJECT>

The following example uses the registered number (CLSID) to create an instance of the Ad Rotator object:

    <OBJECT RUNAT=SERVER ID=MyAds
    CLASS></OBJECT>

## Use Scripting to Create COM Components

ASP supports Windows Script Components, Microsoft's powerful scripting technology that you can use to create COM components. Specifically, you can encapsulate common scripts, such as those used for database access or content generation, into reusable components accessible from any .asp file or program. You can create Windows Script Components by writing scripts in a language such as VBScript or JScript without a special development tool. You can also incorporate Windows Script Components into programs written in COM compliant programming languages, such as Visual Basic, C++, or Java.

The following is an example of a Windows Script Components, written in VBScript, that defines methods for converting temperature measurements between Fahrenheit and Celsius:

    <SCRIPTLET>

    <Registration
        Description="ConvertTemp"
        Prog
        Version="1.00"
    >
    </Registration>

    <implements id=Automation type=Automation>
        <method name=Celsius>
            <PARAMETER name=F/>
        </method>
        <method name=Fahrenheit>
            <PARAMETER name=C/>
        </method>
    </implements>

    <SCRIPT LANGUAGE=VBScript>

      Function Celsius(F)
          Celsius = 5/9 * (F - 32)
      End Function

      Function Fahrenheit(C)
          Fahrenheit = (9/5 * C) + 32
      End Function

    </SCRIPT>
    </SCRIPTLET>

Before implementing this Windows Script Component you must save this file with an .sct extension and then in Windows Explorer, right-click this file and select Register. To use this Windows Script Component in a Web page, you would use a server-side script such as the following:

    <%
      Option Explicit

      Dim objConvert
      Dim sngFvalue, sngCvalue

      sngFvalue = 50
      sngCvalue = 21

      Set objConvert = Server.CreateObject("ConvertTemp.Scriptlet")
    %>

    <%= sngFvalue %> degrees Fahrenheit is equivalent to <%= objConvert.Celsius(sngFvalue) %> degrees Celsius<BR>

    <%= sngCvalue %> degrees Celsius is equivalent to <%= objConvert.Fahrenheit(sngCValue) %> degrees Fahrenheit<BR>

## Using ASP Built-in Objects

ASP also provides built-in objects for performing useful tasks that simplify Web development. For example, you can use the Request object to easily access information associated with an HTTP request, such as user input coming from HTML forms or cookies. Unlike using the objects provided by a COM component, you do not need to create an instance of an ASP built-in object to use it in your scripts. These objects are automatically created for you when the ASP request starts processing. You access the methods and properties of a built-in object in the same way in which you access the methods and properties of a component's objects, as described in this topic. For a complete description of the built-in objects, see ASP Object Quick Reference Card.

## Calling an Object Method

A method is an action you can perform on an object or with an object. The syntax for calling a method is:

Object.Method parameters

The parameters vary depending on the method.

For example, you can use the Write method of the Response built-in object to send information to the browser as shown in the following statement:

    <% Response.Write "Hello World" %>

Note Some scripting languages do not support the Object.Method syntax. If your language does not, you must add an entry to the registry in order to use that language as your primary scripting language. See Working with Scripting Languages for more information.

## Setting an Object Property

A property is an attribute that describes the object. Properties define object characteristics, such as the type of the object, or describe the state of an object, such as enabled or disabled. The syntax is:

Object.Property

You can sometimes read and set the value of a property. In addition, for some objects, you can also add new properties.

For example, the Ad Rotator component has a property, Border, which specifies whether the ad has a border around it and determines the border thickness. The following expression specifies no border:

    <% MyAds.Border = 0 %>

For some properties, you can display the current value by using the ASP output directive. For example, the following statement returns TRUE if the browser is still connected to the server:

    <%= Response.IsClientConnected %>

## Creating an Object from a Java Class

To use Server.CreateObject to create an instance of a Java class, you must use the JavaReg program to register the class as a COM component. You can then use Server.CreateObject method or an HTML <OBJECT> tag with the PROGID or CLSID.

Alternatively, you can use the mechanism provided by Java monikers to instantiate the Java class directly without using the JavaReg program. To instantiate a class with monikers, use the VBScript or JScript GetObject statement and provide the full name of the Java class in the form `java:classname`. The following VBScript example creates an instance of the Java Date class.

    <%
      Dim dtmDate
      Set dtmDate = GetObject("java:java.util.Date")
    %>

    The date is <%= dtmDate.toString() %>

Objects created by calling GetObject instead of Server.CreateObject can also access the ASP built-in objects and participate in a transaction. To use Java monikers, however, you must be using version 2.0, or later, of the Microsoft virtual machine.

© 1997-2001 Microsoft Corporation. All rights reserved.