IProfileService2::Initialize Method [C++]

  • Article

Use this method to establish a connection to the Commerce Server Profiles store and populate the schema cache with all the schemas from the specified catalog.

Definition

[C++]

HRESULT IProfileService::Initialize(BSTRsConfigStore,
  BSTRsCatalog);

[Visual Basic]

Sub Initialize(sConfigStore As String,
  OptionalsCatalog As String)

Parameters

  • sConfigStore[C++]
    [in] A BSTR that contains the connection string to the Profiles store.
  • sConfigStore[Visual Basic]
    [in] A String that contains the connection string to the Profiles store.
  • sCatalog[C++]
    [in, optional] A BSTR that identifies the catalog. If this is specified it must be "Profile Definitions".
  • sCatalog[Visual Basic]
    [in, optional] A String that identifies the catalog. If this is specified it must be "Profile Definitions".

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

The Initialize method creates the necessary internal parameters and schema cache for profile management. A ProfileService object must connect to only one Profiles store. Multiple instances of the ProfileService object must be created to access multiple stores.

The connection string for the Profiles store may be obtained through the SiteConfigReadOnly object, or through the Commerce Server Manager console from the s_ProfileServiceConnectionString property under the key "Commerce Server Manager\Global Resources\Profiles(ComputerName SiteName)".

The connection string is comprised of the following mandatory tokens:

  • Data Source and/or Database [mandatory]. This attribute allows applications to specify the name of the underlying SQL Server containing the Profiles database. At least one of these attributes must be specified. If both of these attributes are specified, the value of the Data Source attribute takes precedence.
  • Initial Catalog and/or Server [mandatory]. This attribute allows applications to specify the name of the Profiles database containing profile definitions. At least one of these attributes must be specified. If both of these attributes are specified, the value of the Initial Catalog attribute takes precedence.
  • User ID and/or UID [mandatory]. This attribute allows applications to specify the login name to connect to the Profiles database. At least one of these attributes must be specified. If both of these attributes are specified, the value of the User ID attribute takes precedence.

The following is a sample connection string containing these attributes:

   Data Source=servername;Initial Catalog=dbname;User ID=user

Spaces are not allowed around the delimiting semi-colon, and a semi-colon is not allowed in the names of any of the tokens.

Additionally, the following optional tokens are also supported by the Profiles resource. You must set these tokens either in the code or by modifying the connection string in the SourceDef table directly. You cannot set these tokens using the Datalink user interface.

  • Provider [optional]. Allows applications to specify the OLE DB provider to which the Profiles resource connects. This parameter exists for consistency with standard ADO connection strings.

    Default value: CSOLEDB (this is the only acceptable value)

  • Password or PWD [optional]. Allows applications to specify the password for the user specified by the User ID or UID attribute.

    Default value: NULL

  • PsObjectCacheSize [optional]. Allows applications to specify the size of the Profiles resource object cache. This cache stores ProfileObject objects instantiated by the CreateProfile and GetProfile methods.

    Default value: 16384 profile objects to cache.

    Minimum value: there is none (it can be set as low as 1, although this configuration does not make sense). Setting this value to 0 (zero) does not disable caching.

    Maximum value: no enforced maximum.

  • PsSchemaCacheSize [optional]. Allows applications to specify the size of the Profile resource definition (schema) cache in entries. This property rarely needs to be changed.

    Acceptable range of values: 1 to 1024 profile objects to cache.

    Default value: 128 profile objects to cache.

    Maximum value: A warning will be posted to the Event log if the number of entries exceeds 1024 profile objects to cache.

  • PsBackgroundThread [optional]. Allows applications to control the creation of a background thread to periodically clean up entries from the Profiles resource object cache.

    Acceptable values for this parameter: 0 disables the background thread, 1 enables it.

    Default value: 1, the background thread is enabled.

  • PsObjectAgeoutPeriod [optional]. Allows applications to specify the age-out period for the Profiles resource cache entries. The age-out period is the amount of time, in milliseconds, that an unreferenced object can remain in the cache without being discarded.

    Default value: Five minutes (300000 milliseconds)

    Maximum value: 1 hour (3600000 milliseconds)

  • Integrated Security [optional]. Allows applications to connect to the Profile Service using integrated windows authentication. The value for this token should be SSPI. When this token is specified the values for User ID/UID and Password/PWD tokens are ignored.

  • Site Name [optional]. Allows applications to specify the site name under which the Profile Service counters should be logged. If no value is specified the performance counters are logged under Anonymous.

  • Connection_Retry [optional]. Allows the applications to specify the number of retry attempts if the connection to the Profile definition store is lost due to a communication failure.

    Default value: 10 retry attempts.

  • Connection_Retry_Delay [optional]. Allows the applications to specify the delay in seconds between retry attempts if the connection to the Profile definition store is lost due to a communication failure.

    Default value: 30 seconds between retry attempts.

  • PublicKey [optional]. This token allows the applications to specify the public key if any of the profiles defined use asymmetric encryption. The value for the token should be a hexadecimal string representation of the Public Key. The value should not be enclosed in quotes.

  • KeyIndex [optional]. This token is mandatory if the PublicKey is specified. Since Public and Privtate keys come in pairs, this token allows the applications to specify which PrivateKey token value corresponds to the PublicKey token.

  • PrivateKey1 [optional]. This token allows the applications to specify the Private key for decryption. The value for this token should be specified if the current key index is 1 and should correspond to the PublicKey. The value for the token should be a hexadecimal string representation of the Private Key. The value should not be enclosed in quotes.

  • PrivateKey2 [optional]. This token allows the applications to specify the Private key for decryption. The value for this token should be specified if the current key index is 1 and should correspond to the PublicKey. The value for the token should be a hexadecimal string representation of the Private Key. The value should not be enclosed in quotes.

Ee809960.note(en-US,CS.20).gif Notes

  • The Initial Catalog in the connection string is the database containing the Profiles store.
  • The sCatalog parameter in the Initialize method is the catalog containing the profile schema definitions, which is "Profile Definitions".

The background thread removes the aged-out objects periodically from the cache. This means that the object may remain in the cache beyond the object age-out period. In this case, the object will be removed from the cache when the background thread processing resumes.

For additional information about the Profiles cache and other Commerce Server caches, see “Refreshing Commerce Server Caches,” at https://go.microsoft.com/fwlink/?LinkId=15097.For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' Connect using an explicit connection string.
' oProfileService is a Commerce ProfileService object

oProfileService.Initialize "Provider=CSOLEDB;Data Source=MyServer;" _
 & "Initial Catalog=Retail_commerce;Integrated Security='SSPI';" _
 & "PsSchemaCacheSize=128;PsObjectAgeoutPeriod=8", "Profile Definitions"

' Connect through the SiteConfigReadOnly object.
' sConn is a String
' oSCRO is an initialized SiteConfigReadOnly object

sConn = oSCRO.Fields("Profiles(ComputerName SiteName").Value _
 .Fields("s_ProfileServiceConnectionString").Value & "SCHCACHE=128"
oProfileService.Initialize sConn, "Profile Definitions"

See Also

[C++]ProfileService Object

[Visual Basic]ProfileService Object

Copyright © 2005 Microsoft Corporation.
All rights reserved.