Before You Start Developing with the Profiles System
For the latest version of Commerce Server 2007 Help, see the Microsoft Web site.
This topic introduces broad concepts about the Commerce Server Profiles System, and provides a context for the detailed information in other topics within this section.
Profiles in Commerce Server represent business objects. When you create a new profile definition, you specify profile properties that instances of the profile will have. When you create an instance of a profile, you provide values for the properties. Users, credit cards, and purchase orders are all examples of business objects that are represented by using profiles. The user profile, for example, includes a property for the logon ID. A specific instance of a user might have the logon ID "MyLogonID."
You define and manage site terms by using the Profiles System. A site term is a set of valid values for information that the user provides. For example, if you added a custom property named "Gender" to the definition of the profile named "User", you could define a site term to represent the values "male" and "female". This would provide the valid values for the "Gender" property.
The Profiles System also implements authentication functionality. Authentication is the process of verifying the identity of a user.
How Commerce Server Implements Profiles
You implement profiles as objects, and map profile properties to the underlying data source in which the values of the properties are stored. As a developer, you access the profile objects from your custom code. You do not access the underlying data sources directly. For more information about how to map profiles to data sources, see How to Create a Profile Definition.
You can store profile data in several different data sources. The data sources can be Microsoft SQL Server or Active Directory. You can store several properties of one profile in one data source, and other properties of the same profile in a different data source. You can also partition your data so that some instances of a specified profile reside in one data source, and other instances of the same profile reside in a different data source. Because you work with profiles as objects, the underlying data sources and distribution of data is hidden from your code.
How the Commerce Server Profiles System Authenticates to SQL Server
By default, Commerce Server uses Windows authentication when it connects to a SQL Server database. If you use Windows authentication it could cause the Profiles System to experience excessive opening and closing of connections to the database. This will affect performance. You have two options to overcome the potential performance impact:
Connect to your Commerce Server databases by using SQL Server authentication instead of Windows authentication. However, SQL Server authentication is not the recommended security practice.
Connect to your Commerce Server databases by using Windows authentication, but make a change in the Windows registry. Commerce Server checks a value for a Windows registry setting that is named UnsafeAuthenticatedConnectionSharing. This registry value is located in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Commerce Server 2007\Profiles. If the value of this setting is 0 (which is the default), Commerce Server logs on and off SQL Server every time that it accesses a user profile. To enhance performance, change this setting to a non-zero value. This will cause Commerce Server to share connections to SQL Server instead of logging on and off. However, changing the setting from the default value of 0 should only be done when impersonation is not configured in the Web application. If impersonation is configured in the Web application, connection sharing becomes enabled. Therefore a connection that is established under one user security context can be reused in another user's session.
Note
You must execute the IISReset command to enable the registry change to take effect.
Note
For profiles, the connection string is located in the Global Resources section of the Commerce Server Manager. Profile connection strings are defined at the global level, unlike other services such as Inventory, Marketing and Product Catalog, which are defined in the Site Resources, not Global Resources.
Why Use the Commerce Server Profiles System
By using the Profiles System, you can obtain several important benefits without implementing custom code. The Profiles System was designed to provide the following:
Scalability. You can partition your data to store some instances of a profile in one data source, and other instances of the same profile in a different data source.
Data aggregation. You can store different properties of the same profile in different data sources. For example, you might store frequently changing data such as the customer's click history in SQL Server, and more static data such as the customer's logon ID in the Active Directory directory service.
Data abstraction. Because you access profiles in your code by using an object model, your code does not have to refer to the structure of the underlying data source.
Personalization. The predefined profile for a customer is integrated with the Commerce Server Marketing System to let you personalize e-mail messages and create marketing campaigns that are targeted to customers who have specific characteristics.
Security. You can encrypt sensitive profile properties, such as passwords, by using a one-way hash. You can use two-way encryption to send sensitive information over a network.
Single source for information. You can obtain all information about a customer from the customer's profile, regardless of where the information is stored.
Programmatically Accessing the Profiles System
The following illustration shows the high-level architecture of the Profiles System.
.gif "Four Ways to Access the Profiles System Programmat")
The following list describes four ways that you can access the Profiles System from your code:
Through the ProfileManagementContext class. This is the recommended way to interact with the Profiles System from business applications that run throughout your corporate network.
Directly through the Web service. This is the interface for business applications that are not Microsoft Windows-based.
Through the ProfileContext class. This is the interface for site code that runs on the Commerce Server server.
Through the CSOLEDB OLE database provider for bulk database operations.
For more information about how to access the Profiles System, see Understanding the Different Types of Commerce Server APIs.
Programming the Profiles Web Service
The following list outlines some special considerations for programming the Profiles Web service:
When you pass GUID values to Commerce Server, you must enclose them in braces "{}". For example, you would pass a GUID value as "{2eebde25-6e56-4122-a8a2-ea0f4324c3ab}" instead of "2eebde25-6e56-4122-a8a2-ea0f4324c3ab".
All data that is passed to the Profiles Web service must be in a culture-invariant format. For example, if you are updating a profile's XML with a Date/Time property, that property value must be formatted as a culture-invariant DateTime. In other words, a valid value would be "07/24/2001". Invalid examples include "24/07/2001" (fr-FR) and "2001/07/24" (ja-JP).
Changes in the Profiles System from Commerce Server 2002
Commerce Server 2007 changes the way the UserProfile property manages caching in the Profiles System. To illustrate this point, consider the following code:
// Profile 1
CommerceContext.Current.UserID = "User1";
Profile profile1 = CommerceContext.Current.UserProfile;
// Profile 2
CommerceContext.Current.UserID = "User2";
Profile profile2 = CommerceContext.Current.UserProfile;
In Commerce Server 2002, the profile1 and profile2 objects both reference the "User1" profile because the first setting of the UserID property would be cached in the Profiles System. In Commerce Server 2007, the profile1 object references the "User1" profile and the profile2 object references the "User2" profile.
Note
It is recommended not to set the UserProfile property. We recommend that you set the UserID property instead and let Commerce Server 2007 automatically update the UserProfile property automatically.
Other Issues
The following list outlines miscellaneous considerations for developers to consider when they program by using the Profiles System:
If the underlying SQL Server data type for a property is NTEXT or BINARY, Commerce Server cannot search the values that are stored in these fields. If you try to search these fields, the following exception error will occur:
"The data value could not be converted for reasons other than sign mismatch or data overflow. For example, the data was corrupted in the data store but the row was still retrievable."
The ProfileContext object is initialized by the Commerce Server initialization module. Developers should not initialize the ProfileContext object on every Web page. Instead, you should create this object one time and use it globally throughout your application. If you use the starter site or the CSharpSite, the Commerce Server initialization module instantiates the ProfileContext object automatically.
The number of instantiated ProfileContext objects is tracked by Commerce Server and generates a warning in the event log on the server if the number of objects exceeds a threshold value. The threshold value can be set in the Windows registry under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Commerce Server 2007. By default, the threshold registry entry is called ExcessiveUseWarnLevel and is set to 100. This means that after one hundred ProfileContext objects are created, a warning is generated in the Windows event log. If you want Commerce Server to also generate an exception when this threshold is reached, set the ThrowExceptionOnExcessiveUse registry entry value to 1. The warning looks as follows:
Event Type:Warning
Event Source:Commerce Server
Event Category:None
Event ID:4116
Date:2/20/2006
Time:2:40:07 PM
User:N/A
Computer:MARTRED
Description:
The Commerce Server runtime has detected that more than 100 instances of the ProfileContext object have been created. If you create many ProfileContext instances, you will adversely affect the performance of the site. Refer to the Commerce Server 2007 documentation for the recommended use of the ProfileContext object.