Core Object Programming Concepts
The following objects are considered general purpose, and can be used in many contexts within Commerce Server:
- AdminEventLog Object
- AdminFiles Object
- AppFrameWork Object
- AuthManager Object
- BizDeskSecurity Object
- DataFunctions Object
- Dictionary Object
- EuroDisplay Object
- GenID Object
- MessageManager Object
- SimpleList Object
AdminEventLog Object
The AdminEventLog object is used to write error, informational, and warning messages to the event log, which can be viewed in the Commerce Server Manager Event Viewer snap-in.
For more information, see AdminEventLog Object.
AdminFiles Object
The AdminFiles object is used to return the contents of a file on the server. The file contents can be of any type, such as text, bitmaps, numeric data, and so on.
For more information, see AdminFiles Object.
AppFrameWork Object
The AppFrameWork object replaces much of the functionality of the Page object, the latter of which will not be supported in future releases. The Page object must be created on every page; in contrast, the AppFrameWork object has better performance because it is created once in the Global.asa file and can be used on any page.
The majority of the methods for the AppFrameWork object have names that begin with Request. These methods apply locale-based data type conversion and data range checking to data retrieved from a browser request. There are two ways to send data from a browser to a server: Data can be appended to the request URL as a query string (for example, https://servername/mysite/default.asp?keyword=books) or it can be posted via forms. Performing these operations on user input ensures that the input data retrieved by an Active Server Pages (ASP) page can be inserted without error into the database storage for the site or passed to the Order Processing pipeline (OPP) in an OrderForm object without generating pipeline or page syntax errors.
Object Dependencies
Because the Request methods of the AppFrameWork and Page object rely on the DataFunctions object for method implementation, you must create the DataFunctions object before you create an AppFrameWork object or a Page object.
The following table shows the values returned by Request methods under different conditions.
| Condition | Method returns |
|---|---|
| The key/value pair is present on request and is valid. | The key value returned from the URL query string or form-post variable. |
| The value returned is empty or Null (for example, the user did not type a value for a search key), or the value is of the wrong type. | The default value (Null, or the value specified by the Default parameter). |
| The value returned is out of the specified range. | Null. |
| The value returned is invalid according to the rules for the locale. | Null. |
AuthManager Object
The AuthManager object identifies users and gathers information used for user authentication. The methods and properties of this object control and access the contents of cookies and encoded URL strings. For more information, see AuthManager Object.
Authentication uses tickets, a string of property/value pairs, to provide information about the user. Two types of tickets are supported, an MSCSAuth ticket and an MSCSProfile ticket. Their differences are summarized in the following table.
| Characteristics | MSCSAuth | MSCSProfile |
|---|---|---|
| Storage | Session cookie/encoded URL string | Persistent cookie/encoded URL string |
| User Type | Registered | Anonymous |
| Contents | Unique user ID, last login time, time window | Unique user ID |
In this context, registered refers to a user who has successfully completed a registration process for the relevant site.
The AuthManager object provides methods to place the ticket into a cookie, if cookies are enabled on the client, or, if cookies are not enabled, into an encoded URL string. When used with the AuthFilter ISAPI filter, cookies must be enabled.
For an MSCSAuth ticket, the AuthManager object can check the validity of the ticket using the IsAuthenticated method. This method checks whether the request from the user contains an MSCSAuth ticket. If it does, the method checks the current time against the last login time set on the ticket to see if it is within the time window specified in the ticket. If it is, the method returns True, indicating a valid MSCSAuth ticket. If the current time is within five minutes of the last login time plus the time window, the last login time on the ticket is changed to the current time so the active user can remain browsing.
A user may have both types of tickets. In this case, the MSCSAuth ticket takes precedence.
If the user does not allow cookies, the ticket is placed in an encoded URL string. The URL string may be used to pass user information between pages and Web sites, provided all the URLs and query strings are generated by the AuthManager object.
The AuthManager object provides a transparent interface to the tickets, whether they are stored in cookies or in URL query strings, and handles encryption and decryption of the tickets to ensure security.
The AuthManager object must be used with ASP since it depends on ASP intrinsic objects. Do not create the AuthManager object in application scope as it has dependencies on individual user sessions. The AuthManager object should be created and destroyed on each ASP page.
BizDeskSecurity Object
The Commerce Server Business Desk security infrastructure allows individual Business Desk modules to be displayed or hidden, depending on the credentials of the user. The CanUserAccess method of the BizDeskSecurity object returns True if the current user has read access rights for a specified Business Desk module. This method retrieves the access rights for the user from the access control list (ACL) for the file. For more information, see BizDeskSecurity Object.
The Active Server Pages (ASP) file corresponding to a Business Desk module is found in the id attribute of the module element of the XML file for the module. The XML file for each module is found in the Config folder located under the Business Desk application folder. For more information about the XML format, see Module Configuration Files.
DataFunctions Object
The DataFunctions object performs locale-based data type handling and value range checking on values that you submit to the database or that you pass in an OrderGroup object to the Order Processing pipeline (OPP).
The DataFunctions object is usually created in the Global.asa file. Use the Active Server Pages (ASP) Server object CreateObject method to create a DataFunctions object, as follows:
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Initialize the object after instantiation
MSCSDataFunctions.Locale = dictConfig.i_SiteDefaultLocale
Also, store the new object in the Application object in the Global.asa file, as follows:
Set Application("MSCSDataFunctions") = MSCSDataFunctions
The AppFrameWork and Page objects have a direct dependency on the DataFunctions object; the DataFunctions object must be created before an AppFrameWork object or a Page object is created.
Dictionary Object
A Commerce Server Dictionary object is a collection object that supports the creation, storage, and retrieval of key/value pairs in memory. Every element in a Dictionary object is a Variant, which means you can create a Dictionary object that consists of almost any kind of values (including other Dictionary objects), and that you can store any combination of Variant types in the same Dictionary object.
The Commerce Server architecture uses the Dictionary object for a number of specialized purposes, including the SiteConfig object. However, because a Dictionary object is designed to be a general purpose collection, you can use it for almost anything that its internal structure supports.
For more information, see Dictionary Object.
EuroDisplay Object
The EuroDisplay object can be used to convert and format currencies. It was originally designed to handle use of the Euro currency, but it can be used for conversion between any two currencies. This object provides convenient currency conversion functionality.
GenID Object
This object is used to generate globally unique identifiers (GUIDs).
For more information, see GenID Object.
MessageManager Object
The MessageManager object stores error messages in multiple languages that the Order Processing pipeline (OPP) components use to describe error conditions generated during OrderForm object processing.
SimpleList Object
A Commerce Server SimpleList object consists of an array of Variants that supports enumeration and access by index. The SimpleList object is used extensively throughout Commerce Server. Use a SimpleList object instead of a Dictionary object in circumstances where accessing the stored content by index is important.
For more information, see SimpleList Object.
Copyright © 2005 Microsoft Corporation.
All rights reserved.