[This is preliminary documentation and subject to change]

# Setting Object Scope

The scope of an object determines which scripts can use that object. By default, when you create an object instance, the object has page scope. Any script command in the same ASP page can use a page-scope object; the object is released when the .asp file completes processing the request. The recommended scope for most objects is page scope. You can change the scope of an object, however, to make it accessible from scripts on other pages. This topic explains how to work with page scope objects and how to change the scope of objects.

## Using Page Scope Objects

An object that you create by using Server.CreateObject or the HTML <OBJECT> tag on an ASP page exists for the duration of that page. The object is accessible to any script commands on that page, and it is released when ASP has finished processing the page. Thus an object has the scope, or lifetime, of a page.

### Creating Objects in Loops

In general, you should avoid creating objects inside a loop. If you must create objects in a loop, you should manually release the resources used by an object:

    <%
      Dim objAd
      For i = 0 To 1000
        Set objAd = Server.CreateObject("MSWC.AdRotator")
        .
        .
        .
        objAd.GetAdvertisement
        .
        .
        .
        Set objAd = Nothing
      Next
    %>

## Giving an Object Session Scope

A session-scope object is created for each new session in an application and released when the session ends; thus, there is one object per active session. Session scope is used for objects that are called from multiple scripts but affect one user session. You should give objects session scope only when needed. If you do use session scope, you must know the threading model of the component that provides the object because the threading model affects the performance and security context of the object. For more information, see Advanced Information: Performance Issues in this topic.

To give an object session scope, store the object in the ASP Session built-in object. You can use either the HTML <OBJECT> tag in a Global.asa file or the Server.CreateObject method on an ASP page to create a session scope object instance.

In the Global.asa file, you can use the <OBJECT> tag, extended with RUNAT attribute (which must be set to SERVER) and the SCOPE attribute (which must be set to Session). The following example creates a session-scope instance of the Browser Type object of the Browser Capabilities component:

    <OBJECT RUNAT=SERVER SCOPE=Session ID=MyBrowser PROG>
    </OBJECT>

Once you have stored the object in the Session object, you can access the object from any page in the application. The following statement uses the object instance created by the <OBJECT> tag in the previous example:

    <%= If MyBrowser.browser = "IE"  and  MyBrowser.majorver >= 4  Then . . .%>

On an ASP page, you can also use the Server.CreateObject method to store an object in the Session built-in object. The following example stores an instance of the Browser Type object in the Session object.

    <% Set Session("MyBrowser") = Server.CreateObject("MSWC.BrowserType") %>

To display browser information in a different .asp file, you first retrieve the instance of the BrowserType object stored in the Session object, and then call the Browser method to display the name of the browser:

    <% Set MyBrowser = Session("MyBrowser") %>
    <%= MyBrowser.browser %>

ASP does not instantiate an object that you declare with the <OBJECT> tag until that object is referenced by a script command from an .asp file. The Server.CreateObject method instantiates the object immediately. Thus, the <OBJECT> tag offers better scalability than the Server.CreateObject method for session-scope objects.

## Giving an Object Application Scope

An application-scope object is a single instance of an object that is created when the application starts. This object is shared by all client requests. Some utility objects, such as the objects of the Page Counter Component, might perform better in application scope, but generally you should use the alternatives proposed in the following section. In addition, the threading model affects the performance and security context of the object (see Advanced Information: Performance Issues in this topic).

To give an object application scope, store the object in the ASP Application built-in object. You can use either the <OBJECT> tag in a Global.asa file or the Server.CreateObject method in an .asp file to create an application scope object instance.

In the Global.asa file, you can use the <OBJECT> tag, extended with RUNAT attribute (which must be set to Server) and the SCOPE attribute (which must be set to Application). For example, the following is an example of using the <OBJECT> tag to create an application-scope instance of the Ad Rotator object:

    <OBJECT RUNAT=SERVER SCOPE=Application ID=MyAds PROG>
    </OBJECT>

After storing the Ad Rotator object in Application state, you can access from any page in you application using a statement such as the following:

    <%=MyAds.GetAdvertisement("CustomerAds.txt") %>

Alternatively, in an .asp file, you can use Server.CreateObject to store an object instance in the Application built-in object, such as in the following example:

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

You can display the advertisement in your application's .asp files by retrieving the instance of the Ad Rotator object from Application state, as in the following example:

<%Set MyAds = Application("MyAds") %> <%=MyAds.GetAdvertisement("CustomerAds.txt") %>

## Alternatives to Session and Application Scope

In general, you should try to extensively use application or session state for items or objects that take a long time to initialize, such as dictionary objects or recordsets. However, if you find that objects in session or application state are consuming too many resources, such as memory or database connections, you should seek alternative ways to implement these objects. For example, the threading model of a component can affect the performance of objects you create from it, especially objects with session or application scope.

In many cases, a better solution than creating application or session scope objects is to use session or application scope variables that pass information to objects created at the page level. For example, you should not give an ADO Connection object session or application scope because the connection it creates remains open for a long time and because your script no longer takes advantage of connection pooling. You can, however, store an ODBC or OLE DB connection string in the Session or Application built-in object and access the string to set a property on the Connection object instance that you create on a page. In this way, you store frequently used information in session or application state but you create the object that uses the information only when needed. For more information about scoping variables, see Using Variables and Constants.

## User-Defined JScript Objects

You can create your own JScript object by defining a constructor function that creates and initializes the properties and methods of the new object. The object instance is created when your script uses the new operator to invoke the constructor. User-defined JScript objects are supported in ASP server-side scripts and work well when they have page scope. However, you cannot give a user-defined object application scope. Also, giving a user-defined JScript object session scope may affect the functionality of the object. In particular, if an object has session scope, scripts on other pages can access the object's properties but cannot call its methods. Also, giving a user-defined JScript object session scope can affect Web application performance.

## Advanced Information: Performance Issues

The threading model of a component may affect the performance of your Web site. Generally, objects that are marked Both are the recommended objects to use in .asp files if they will be stored in Session and Application state. Single-threaded, Apartment, and free-threaded objects are not recommended.

Because you may not always have control over the threading model of the objects you use, the following guidelines will help you get the best performance:

- Page scope objects Objects marked Both or Apartment will give you the best performance.
- Application scope objects Objects marked Both, that also aggregate the FreeThreadedMarshaler, will give you the best performance. You can use either the <OBJECT> tag or the Server.CreateObject method to store objects marked Both in the Application object. You must use the HTML <OBJECT> tag with apartment-threaded objects.
- Session scope objects Objects marked Both will give you the best performance. Using single-threaded or apartment-threaded objects will cause the Web server to lock the session down to one thread. Free-threaded objects do not lock down the session, but are slow. You can use either the <OBJECT> tag or the Server.CreateObject method to store objects in the Session object.

For more information on threading models and their implications for component performance, refer to the topic titled Building Components for ASP in the MSDN Online Library.

© 1997-2001 Microsoft Corporation. All rights reserved.