Vinayak's WebLog : Programming the Catalog System

Adding multilingual display names to property definitions

vinayakt — Sat, 07 Oct 2006 09:22:00 GMT

The Commerce Server 2007 catalog system supports multilingual display names for Property definitions, catalog definitions, products, categories and variants. This post discusses multilingual display name support for property definitions.

The following are the steps to add multilingual display names for property definitions

Add the desired langauges to the property definitions
Set the display names for the desired property.

While the above steps can be performed from the Catalog and Inventory Schema Manager, you can programatically achieve this as follows:

/// <summary>

/// Language support for property definitions

/// </summary>

/// <param name="catalogContext"></param>

internal void AddLanguagesToPropertyDefinitions(CatalogContext

catalogContext)

{

// Add the languages to the Property definitions

catalogContext.AddLanguageToPropertyDefinitions("en-US");

catalogContext.AddLanguageToPropertyDefinitions("fr-FR");

// Get the langauges added to the Property definitions

foreach(string language in

catalogContext.GetPropertyDefinitionLanguages())

{

Console.WriteLine(language);

}

// To set the displaynames for properties

// Get the CatalogProperty object

CatalogProperty property = catalogContext.GetProperty("Name");

// For a language X, you can get/set the display name in the

// DisplayName_X property

property["DisplayName_en-US"] = "Name";

property["DisplayName_fr-FR"] = "Nom";

// Save the displaynames

property.Save();

// Get the English display names

string displayNameEn = null;

// Ensure that the property exists and it has a value

if ( property.HasProperty("DisplayName_en-US") &&

!property.IsPropertyNull("DisplayName_en-US"))

{

displayNameEn = (string)property["DisplayName_en-US"];

}

// Remove the language

catalogContext.RemoveLanguageFromPropertyDefinitions("fr-FR");

}

Extending the entites in the Catalog and Inventory Systems

vinayakt — Fri, 06 Oct 2006 11:14:00 GMT

Commerce Server 2007 allows you to extend the different entities in the Catalog and Inventory systems in a straightforward manner. These are the various entities that can be extended

Property Definitions
Catalog Definitions
Inventory Catalog
Inventory Skus
Product and Categories

All the above entities except 5 can be extended as follows

Create a property. For eg if you want to associate a VendorId with a catalog, create a property named VendorId of datatype string.
Add the property to the appropriate entity
Once the entity has been added to the entity you can access its value using the indexer or the corresponding dataset. For eg. string vendorId = (string)productCatalog["VendorId"];
You can also enumerate the list of properties added to a particular entity
Note that multilingual properties cannot be added to the first four entities
If your site contains an inventory resource then the properties defined in the catalog system can be used to extend the Inventory Catalog and Inventry Skus entities

The above operations can be performed from the Catalog and Inventory Schema manager. This is how you can perform the above tasks programatically.

Assume that you want to add a VendorId property to track vendors for your product catalogs

/// <summary>

/// Extends the ProductCatalog Entity

/// </summary>

/// <param name="catalogContext"></param>

internal void ExtendCatalogEntity(CatalogContext catalogContext)

{

// Create the property

CatalogProperty property = catalogContext.CreateProperty("VendorId",

CatalogDataType.String, 25);

// Add the property to the ExtensibleEntityType.ProductCatalog entity

catalogContext.AddPropertyToEntity(ExtensibleEntityType.ProductCatalog,

"VendorId");

// Get the properties added to the ExtensibleEntityType.ProductCatalog entity

CatalogPropertiesDataSet extendedProperties =

catalogContext.GetEntityProperties(ExtensibleEntityType.ProductCatalog);

// Iterate through all the extended properties

foreach(CatalogPropertiesDataSet.CatalogProperty extendedProperty in

extendedProperties.CatalogProperties)

{

string propertyName = extendedProperty.PropertyName;

}

// Now assign a value to the VendorId

ProductCatalog productCatalog = catalogContext.GetCatalog("My Catalog");

productCatalog["VendorId"] = "My Vendor";

// You can also use the Information property to do the same thing

// productCatalog.Information.Catalogs[0]["VendorId"] = "My Vendor";

// save the changes

productCatalog.Save();

string vendorId = null;

// Access the value of the "VendorId" property

// Validate that "VendorId" property has been added to the ProductCatalog

// entity and its value is not null

if ( productCatalog.HasProperty("VendorId")

&& !productCatalog.IsPropertyNull("VendorId"))

{

vendorId = (string)productCatalog["VendorId"];

// vendorId = (string)productCatalog.Information.Catalogs[0]["VendorId"];

}

// Remove the property from the ProductCatalog entity

catalogContext.RemovePropertyFromEntity(ExtensibleEntityType.ProductCatalog,

"VendorId");

}

In a similar manner you can extend the other entities. Use

ExtensibleEntityType.PropertyDefinition for Property Definitions
ExtensibleEntityType.ProductCatalog for Catalog Definitions
ExtensibleEntityType.InventoryCatalog for Inventory Catalog
ExtensibleEntityType.InventorySku for Inventory Skus

Implementing the credential prompter

vinayakt — Wed, 06 Sep 2006 08:14:00 GMT

I received a question on my earlier post on implementing the credential prompter. When connecting to the web service you have to specify a CatalogServiceAgent object. When authenticating against a Web service, the default behavior is to first try to make Web service method calls without any authentication credentials. If an Authentication related exception results (e.g. HTTP 401 response from the Web server), then the next step is to try using the user's default credentials, if available. If those credentials are not available or also fail, and the CatalogServiceAgent has been provided with an IPromptForCredentials implementation, then the IPromptForCredentials.PromptForCredentials method is invoked to retrieve alternate credentials for the user. This typically involves displaying a dialog box to a user in order to prompt them to input new credentials. These credentials are then cached in a System.Net.CredentialCache object and re-used when issuing further method calls against the service.

A sample implementation of the credential prompter whcih prompts the user for the login name and password can be done as follows:

internal class UserCredentialPrompter : IPromptForCredentials

{

public NetworkCredential PromptForCredentials(string url,

string authType)

{

// Set the network credentials

NetworkCredential myCredentials = null;

// Launch dialog to capture the user name and password

// Show the Login dialog

DialogResult result = form.ShowDialog();

if (result == DialogResult.OK)

{

// Create the NetworkCredential based on user input

myCredentials = new NetworkCredential(form.UserName,

form.Password, form.Domain);

}

// Return the obtained credentials

return myCredentials;

}

You can then instantiate the CatalogServiceAgent as

CatalogServiceAgent catalogServiceAgent = new CatalogServiceAgent(@"http://Servername/CatalogWebservice/CatalogWebservice.asmx", ServiceAgent.DefaultAuthMethods, new UserCredentialPrompter());

CatalogContext context = CatalogContext.Create(catalogServiceAgent);

Programming the Commerce Server 2007 catalog system: Creating the CatalogContext

vinayakt — Wed, 30 Aug 2006 07:15:00 GMT

The objects in the catalog system can now be programmed in two modes. In the first mode the catalog server assembly is loaded in the callers appdomain (aka inproc mode). In the second mode the functionality of the catalog system is available remotely via the catalog web service. The programming model and the methods available in both the modes are the same. The only difference is in the way the CatalogContext object is created. The CatalogContext object is the root object in the catalog system. All other objects are obtained from the CatalogContext object.

1. The Inproc mode : You use this mode when you are running your code on the web server. The CatalogContext code is initialized by specifying the sitename. The following code sample shows how to create a CatalogContext in this mode. You need to add references to the Microsoft.Commerceserver.catalog, Microsoft.CommerceServer.CrossTierTypes and Microsoft.CommerceServer.Shared assemblies. The objects in the catalog system reside in the Microsoft.CommerceServer.Catalog and Microsoft.CommerceServer namespaces.

CatalogSiteAgent siteInfo = new CatalogSiteAgent();

siteInfo.SiteName = "StarterSite";

siteInfo.AuthorizationMode = AuthorizationMode.ThreadContext;

siteInfo.AuthorizationPolicyPath = @"E:\Inetpub\wwwroot\CatalogWebService\CatalogAuthorizationStore.xml";

siteInfo.IgnoreInventorySystem = false;

CacheConfiguration cacheConfiguration = new CacheConfiguration();

cacheConfiguration.CacheEnabled =true;

cacheConfiguration.SchemaCacheTimeout = new TimeSpan(0, 10, 0);

CatalogContext context = CatalogContext.Create(siteInfo, cacheConfiguration);

Use the CatalogSiteAgent class to specify the site name, the authorization information and the inventory usage option.

The AuthorizationMode enumeration has the following values

AuthorizationMode.NoAuthorization : Do not perform any authorization checks. This mode should be used on the runtime sites.
AuthorizationMode.ThreadContext : Before performing any operation ensure that the user is authorized to perform it. The identity of the user is obtained from the user's thread context. This mode should be used in Console applications.
AuthorizationMode.HttpContext : Before performing any operation ensure that the user is authorized to perform it. The identity of the user is obtained from the current Http context. This mode should be used in web applications where users update the catalog system.

The AuthorizationPolicyPath specifies the location of the authorization store. The authorization store is an Xml file which contains which information about the authorized users and the operations they can perform.

Commerce Server 2007 now adds an inventory integration with the catalog system.The inventory system now allows you to store the inventory information like (onhandquantities, status etc) for products and variants in the catalog system. You can use the IgnoreInventorySystem parameter to turn off inventory integration.If the inventory resource exists and IgnoreInventorySystem parameter is set to false no inventory operations or lookups will be performed by the catalog methods.

Use the CacheConfiguration object to specify the caching configuration. Note that caching is turned off by default and is enabled by setting the cacheConfiguration.CacheEnabled property.

If you are using the Microsoft.CommerceServer.Runtime BCL then you can specify the cache configuration and the inventory integration option in the web.config of your runtime site.

2. The WebService mode: The CatalogContext object can also be initialized in the webservice mode by passing in the url of the catalog webservice.

CatalogServiceAgent catalogServiceAgent = new CatalogServiceAgent(@"http://Servername/CatalogWebservice/CatalogWebservice.asmx");

CatalogContext context = CatalogContext.Create(catalogServiceAgent);

Use the CatalogServiceAgent class to specify the url of the catalog web service. The other overloads on this method allow you to specify the authentication methods and a credential prompter.

If you are wondering how to specify the authorization, caching and inventory option this is specified through the catalogWebService element in web.config. All the attributes and child elements are documented in the web.config itself.

Note: Even though the CatalogContext class has the CreateFromConnectionString method, it exists only for backward compatibility and is now deprecated.

Improving the catalog search experience in Commerce Server 2007

vinayakt — Sun, 18 Jun 2006 08:53:00 GMT

Two years back in this post on fulltext search in the catalog system, I had explained how fulltext searches are performed in the catalog system and added the following comment

"Providing an increased number of search features/conditions is something we are looking forward to, in the upcoming releases. This should allow you to specify more complex search phrases."

Commerce Server 2007 now allows you to specify complex search phrases which allow you to customize your searches to the finest level of granularity. If the default freetext search behavior as described in the above link does not work for you, you can now use the new AdvancedFreeTextSearchPhrase property on the CatalogSearch object. An example of using this property to implement Thesaurus support is provided in this link. Note that when you set this property you should also set the UseAdvancedFreeTextSearch to true. This is to avoid ambiguity on whether the value specified for AdvancedFreeTextSearchPhrase or FreeTextSearchPhrase property should be used to perform the search.

Here are some additional search scenarios for which you can use this new property.

You can perform wild card searches by appending * to the search phrase. For eg to return all the products containing search terms beginning with "Commerce". When passing a compound phrase you need to enclose the phrase in quotes.

catalogSearch.AdvancedFreeTextSearchPhrase = "Commerce*"; catalogSearch.AdvancedFreeTextSearchPhrase = "\"Commerce Server*\"";

To perform exact searches you should enclose the phrase in quotes. For eg to return rows that contain the exact phrase "Commerce Server 2007"

catalogSearch.AdvancedFreeTextSearchPhrase = "\"Commerce Server 2007\"";

To return all the products containing the phrases "Commerce Server" and "Sql Server"

catalogSearch.AdvancedFreeTextSearchPhrase=" \"Commerce Server 2007\" AND \"Sql Server\" ";

To return all the products containing the phrases "Commerce Server" OR "Sql Server"

catalogSearch.AdvancedFreeTextSearchPhrase=" \"Commerce Server 2007\" OR \"Sql Server\" ";

To return all products beginning with Commerce Or Sql server

catalogSearch.AdvancedFreeTextSearchPhrase=" Commerce* OR \"Sql Server\" ";

You can also perform proximity searches using the NEAR keyword. For eg to return all products containing the word 2007 near "Commerce Server"

catalogSearch.AdvancedFreeTextSearchPhrase="2007 NEAR \"Commerce Server\"";

You can perform inflectional searches using the INFLECTIONAL keyword. For eg to return all products with forms of dry like drying, dried etc

catalogSearch.AdvancedFreeTextSearchPhrase="FORMSOF (Inflectional,dry)";

To return all products containing Commerce or Sql Server and not ASP

catalogSearch.AdvancedFreeTextSearchPhrase="(\"commerce \" OR \"sql server\") and not ASP\"";

The above are just some of the scenarios. To truly understand what else you can do take a look at this link. Determine the clause which best reflects your search criteria and pass it to the AdvancedFreeTextSearchPhrase as in the above example.

For a complete code sample and additional filtering using other criteria like "list price < $100 AND IsActive=1" see this post.

Implementing Thesaurus support in the catalog system

vinayakt — Mon, 12 Jun 2006 10:44:00 GMT

Sql Server 2005 now provides Thesaurus support through configurable xml files. In a nutshell the Thesaurus feature allows you to search for synonyms of the search phrase or replace the search phrase with a replacement phrase and perform the search using the replacement phrase. These synonyms and replacements can be configured using the xml files.See this link for configuring the xml files.

If you are using Sql Server 2005 as your Commerce Server database server then you can take advantage of this cool feature when performing catalog searches.

As an example, suppose that you have a Books catalog. Assume that Description is a fulltext searchable property in this catalog and that this catalog has various C# books. When performing a search on your site users might search for C# or "C Sharp". You can use the Thesaurus feature to allow searches for "C Sharp" to return C# books.

The first step is to edit the tsENU.xml file located in the SQL_Server_install_path\Microsoft SQL Server\MSSQL.1\MSSQL\FTDATA\ directory and add the following element to it

         <expansion>
                     <sub>C sharp</sub>
                     <sub>C#</sub>
          </expansion>

After you edit the xml file you will have to restart the "SQL Server FullText Search (MSSQLSERVER)" service for the changes to take effect.

The following code sample demonstrates how to perform the catalog search to allow searches for "C Sharp" to return books containing C#:

CatalogSearch catalogSearch = catalogContext.GetCatalogSearch();

catalogSearch.SearchOptions = new CatalogSearchOptions();

// Set appropriate search options

catalogSearch.SearchOptions.SetPaging(1,20);

catalogSearch.UseAdvancedFreeTextSearch = true;

catalogSearch.AdvancedFreeTextSearchPhrase = "FORMSOF(THESAURUS, \"C Sharp\")";

int totalRecords;

CatalogItemsDataSet searchResults = catalogSearch.Search(out totalRecords);

// Iterate through the search results

foreach(CatalogItemsDataSet.CatalogItem searchResult in searchResults.CatalogItems)

Console.WriteLine(searchResult.CategoryName);

Caching in the catalog system

vinayakt — Fri, 02 Jun 2006 07:27:00 GMT

The Commerce Server 2007 catalog system adds a new caching feature which caches frequently used datasets.

What is cached?

In order to prevent repeated calls to the sql server the catalog system caches the results of various methods in the catalog system. These results are cached in the form of datasets. The catalog system uses the System.Web.Caching.Cache object to cache the various datasets. Each dataset is inserted in the cache with the CacheItemPriority.Normal. The time for which a dataset remains in the cache is configurable. If not specified the default time is 5 minutes.

However in order to account for the relative frequency at which different items in the catalog system are changed we have classified the datasets in six different categories allowing you to specify different timeouts. The goal is to ensure allow for items which change less frequently to remain in the cache much longer that those that change more frequently.

The cache configuration can be defined when you create the CatalogContext object

CacheConfiguration cacheConfiguration = new CacheConfiguration();

cacheConfiguration.CacheEnabled = true;

cacheConfiguration.SchemaCacheTimeout = new TimeSpan(0, 10, 0);

cacheConfiguration.ItemAssociationsCacheTimeout = new TimeSpan(0, 10, 0);

cacheConfiguration.ItemHierarchyCacheTimeout = new TimeSpan(0, 10, 0);

cacheConfiguration.ItemInformationCacheTimeout = new TimeSpan(0, 10, 0);

cacheConfiguration.ItemRelationshipsCacheTimeout = new TimeSpan(0, 10, 0);

cacheConfiguration.CatalogCollectionCacheTimeout = new TimeSpan(0, 10, 0);

CatalogSiteAgent siteAgent = new CatalogSiteAgent();

siteAgent.SiteName = "SiteName";

CatalogContext cc = CatalogContext.Create(siteAgent, cacheConfiguration);

Caching is enabled by setting cacheConfiguration.CacheEnabled property to true.

The following are the different categories of datasets and their timeout configuration parameters

CatalogSchema : This applies to datasets that return schema information. These datasets will remain in the cache for the timeout defined by the cacheConfiguration.SchemaCacheTimeout property. Since the catalog schema is less likely to change once it has been defined setting the timeout to a high value can result in improved performance.

The cacheConfiguration.SchemaCacheTimeout applies to the datasets returned by the following properties/methods

CatalogContext.GetProperty()

CatalogContext.GetEntityProperties()

CatalogContext.GetProperties()

CatalogContext.GetSearchableProperties()

CatalogContext.GetPropertiesInCatalog()

ProductCatalog.PropertiesInCatalog

CatalogEnumerationProperty.EnumerationValues

CatalogContext.GetDefinitions()

CatalogDefinition.DefinitionProperties

Item Properties : Almost all the objects in the catalog system expose an Information property which is a dataset containing the properties for that object. For eg ProductCatalog.Information returns a dataset containing the properties of the specified product catalog. The duration the dataset returned by the Information property remains in the cache is controlled by the cacheConfiguration.ItemInformationCacheTimeout property.

The cacheConfiguration.ItemInformationCacheTimeout property applies to the datasets returned by the following properties/methods

CatalogSet.Information

Category.Information

InventoryCatalog.Information

InventorySku.Information

Product.Information

ProductCatalog.Information

ProductVariant.DataRow

Note that this timeout also applies to the product information stored by the QueryCatalogInfo pipeline component.

Another thing to note is that if inventory integration is enabled the inventory information also gets cached.

Catalog Hierarchy : The catalog system allows you to define parent child hierarchies between categories and products. This information is returned in the form of datasets. The duration for which these datasets are cached is determined by the cacheConfiguration.ItemHierarchyCacheTimeout property. The cacheConfiguration.ItemHierarchyCacheTimeout property applies to the following methods/properties :

ProductCatalog.GetRootCategories()

ProductCatalog.GetRootProducts()

Product.AncestorCategories

Category.AncestorCategories

Product.ParentCategories

Category.ParentCategories

Product.CanonicalCategories

Category.CanonicalCategories

Category.Products

Category.ChildCategories

Catalog Relationships : The catalog system allows you to define relationships between products and categories. The duration for which the relationships datasets remain in the cache is determined by the cacheConfiguration. ItemRelationshipsCacheTimeout property and applies to the following properties

Category.RelatedCategories

Product.RelatedCategories

Category.RelatedProducts

Product.RelatedProducts

Associations between different objects: The catalog system allows you to have various types of associations between different objects. For eg product catalogs associated to inventory catalogs, product catalogs to catalog sets, languages associated to product catalogs etc The duration for which these associations datasets remain in the cache is determined by the cacheConfiguration. ItemAssociationsCacheTimeout property and applies to the datasets returned by the following properties:

ProductCatalog.Languages

ProductCatalog.DependentCatalogs

VirtualCatalog.SourceCatalogs

CatalogSet.IncludedCatalogs

CatalogSet.NotIncludedCatalogs

InventoryContext.GetUnassociatedProductCatalogs

InventoryCatalog.AssociatedProductCatalogs

VirtualCatalog.VirtualCatalogRules

VirtualCatalog.PriceRules

Catalog Collections : The cacheConfiguration .CatalogCollectionCacheTimeout property controls how long the following datasets remain in the cache

CatalogContext.GetCatalogs()

InventoryContext.GetInventoryCatalogs()

CatalogSetsContext.GetCatalogSets

Monitoring the Catalog cache using perfmon

If you have enabled caching then you can monitor the perfomace of the cache by observing the following performance counters under Commerce : Catalog set of counters.

1. CacheTotalHits : The total number of cache hits

2. CacheTotalMissess: The total number of cache misses

3. CacheHitRate : The number of cache hits per sec

4. CacheMissRate : The number of cache misses per sec

5. CacheHitRatio : The ratio of the cache hits to the total number of cache accesses. This is equal to CacheTotalHits / (CacheTotalHits + CacheTotalMisses)

6. CacheTurnOverRate : The number of cache insert and deletes per second

Web.Config section for caching

The Caching parameters can also be set in web.config of your runtime site using the following element

<cache

enable="true"

schemaTimeout="10"

itemInformationCacheTimeout ="10"

itemHierarchyCacheTimeout ="10"

itemRelationshipsCacheTimeout = "10"

itemAssociationsCacheTimeout="10"

catalogCollectionCacheTimeout="10"

</catalog>

Here 10 is the duration in minutes, the respective datasets should be in the cache.

Since the catalog system uses the System.Web.Caching.Cache you can tune the different aspects of the catalog cache using the ASP.NET cache settings.

The COM objects in the product catalog system

vinayakt — Sun, 09 Oct 2005 11:26:00 GMT

The Catalog system basically has four main objects:

1. The CatalogManager object is the only externally creatable object. The progid is Commerce.CatalogManager. You can use this object to manage all the catalog schema, create/delete catalogs, import from and export to csv and xml files and search the catalog system.

2. The ProductCatalog object is used to manage an individual catalog in the catalog system. An instance of this object can be obtained by calling the CatalogManager.GetCatalog() method. You can then use the productcatalog object to create/edit/delete products and categories in the catalog.

3. The Category object wraps the functionality of a category in a catalog. An instance of the this object can be obtained by calling the ProductCatalog.GetCategory() method. You can use the category object to update the category properties, add/delete relationships to other categories and products, add/delete parent/child categories, add/delete child products and search the category.

4. The Product object wraps the functionality of a product in a catalog. An instance of the this object can be obtained by calling the ProductCatalog.GetProduct() method. You can use the product object to update the product properties, add/delete relationships to other categories and products, add/delete parent categories and add/delete product variants.

A typical sample for accessing these objects would be :

Dim oCatalogManager
Dim oProductCatalog
Dim oCategory
Dim oProduct

' Create the oCatalogManager object
Set oCatalogManager = CreateObject("Commerce.CatalogManager")
' Initialize the oCatalogManager with the sitename
Call oCatalogManager.Initialize("siteName", false)

' Initialize the oCatalogManager with the connection string to the catalog database
Call oCatalogManager.Initialize("connection string", true)

' Get the productcatalog object
Set oProductCatalog = oCatalogManager.GetCatalog("catalogname")

' Get the category object
Set oCategory= oProductCatalog.GetCategory("categoryname")

' Get the product object
Set oProduct = oProductCatalog.GetProduct("productid")

Some do's and don'ts when using these objects

1. Avoid initializing the CatalogManager object more than once in your application. The CatalogManager object should be initialized once on startup and reused (can be stored in the application state for web applications). If for some reason you have to initialize the CatalogManager object multiple times prefer to initialize it using the connection string. Initializing the CatalogManager object using the siteName is expensive and resource intensive and doing this repeatedly is going to severly impact the performance of your application.

2. When perfroming searches on a catalog specify appropriate paging parameters. See this article on how you can take advantage of some of the optimizations built in the catalog system when doing searches. The underlying stored procedures are tuned to account for the conditions mentioned in this article.

3. See this article on the correct way to specify input parameters for your search conditions.