Product Catalog System Task and Object Mapping from COM to .NET

  • Article

The COM object model for catalogs includes methods and properties for both design-time and run-time catalog activities. The Microsoft.CommerceServer.Runtime.Catalog namespace exposes only the runtime functionality, and wraps the catalog set functionality.

At the root of the Catalog namespace is the CatalogContext object. A CatalogContext object is loosely similar to a CatalogManager object in COM, with the management functionality removed and the searching functionality factored out into a separate object (the CatalogSearch object). At application startup, the CommerceCatalogModule creates an instance of the CatalogContext object and makes it available at the application level through a static property, CatalogContext, and also to the page through an instance property, CommerceContext.Current.CatalogSystem. If you are not using the Commerce Server .NET Application Framework, then you can create a stand-alone CatalogContext object using the static method CreateFromConnectionString. You can use the SiteConfigReadOnly object to get the connection string for the Product Catalog system for your Commerce Server site.

From a CatalogContext object, you can gain access to the rest of the catalog hierarchy, including the familiar ProductCatalog, Product, and Category objects. You can get a ProductCatalog object from the CatalogContext.GetCatalog method, a Product object from the ProductCatalog.GetProduct method, and a Category object from the ProductCatalog.GetCategory method.

A few things to be aware of include:

  • In the COM-based model, search results were returned through ADO Recordsets. In the .NET-based model, they are returned through ADO.NET datasets or other appropriate structures such as collections.
  • In the COM-based model, searching was available through different objects. These included CatalogManager.Search and Category.Search. The scope of the search was determined by which object you searched. In the .NET-based model, searching is done through a separate object, CatalogSearch, which uses properties that you set to scope the search.
  • In the COM-based model, many of the methods used parameters to allow you to specify how data was to be returned, including items such as sort order and paging parameters. Unfortunately, each of the methods were inconsistent in the set of parameters they accepted. In the .NET-based model this is specified in a more standard and consistent way by providing an instance of the CatalogSearchOptions object. For details about the recognized options for each object, see the reference pages in the .NET Class Reference. The DubugContext object will contain warnings about any settings that are ignored.
  • In the COM-based model, there was a separate object for getting the catalog collection based on the profile of the user. In the .NET-based model, this functionality is exposed by the CommerceContext object.
  • The .NET-based model does not expose the attributes for all the catalog properties in one dataset. You need to get the PropertyNames collection and iterate it to get the property attributes for each property.
  • All the methods for the Product and Category objects that return a Recordset containing the parent or child category information also return the display name for each category in the Recordset. The corresponding methods in the .NET-based model return ReadOnlyStringCollections that do not contain the category display name. You can call the Category.GetCategoryProperties method to get the display names for each category. The one exception to this is Category.GetChildCategories, which returns a dataset.

Object mapping

The .NET types in the following table are in the Microsoft.Commerceserver.Runtime.Catalog namespace unless otherwise noted.

ASP ASP.NET
CatalogManager CatalogContext
ProductCatalog ProductCatalog
Category Category
Product Product
CatalogSets CommerceContext.GetCatalogsForUser
CatalogToVendorAssociation None, use COM Interop (no PIA provided)

Task mapping

Accessing the root Product Catalog System object

Accessing a ProductCatalog object for a specific catalog

Searching for a catalog or catalogs

Getting the list of catalogs that should be available to a particular user using the CatalogSets functionality

Searching for products or categories in a catalog or across catalogs (free-text or property-based)

Searching a specific category for descendent products or categories

Refreshing cached catalog data

Setting the Product Catalog System to join catalog result sets against an external table

Performing a specification search against a catalog

Getting the list of properties that can be displayed on the site

Setting the language on the catalog object

Getting the list of properties in a catalog

Accessing a product in a catalog

Accessing a category in a catalog

Accessing the root category in a catalog

Paging through a list of root categories

Paging through a list of root products

Getting the canonical path of a category to the root

Getting the canonical path of a product to the root

Getting the descendant products for a category

Getting the ancestor categories for a Product

Getting the parent categories for a Product

Getting the ancestor categories for a Category

Getting the parent categories for a Category

Getting the child categories for a Category

Accessing the root Product Catalog System object

ASP ASP.NET
Application(“MSCSCatalogManager”) CommerceContext.Current.CatalogSystem (for page-level access)

CommerceCatalogModule.CatalogContext (for application-level access)

Accessing a ProductCatalog object for a specific catalog

ASP ASP.NET
CatalogManager.GetCatalog CatalogContext.GetCatalog

Searching for a catalog or catalogs

Note that in both the COM and .NET-based models, you get back a result set containing information about the catalogs, but you must still call the GetCatalog method to access the ProductCatalog objects themselves.

ASP ASP.NET
CatalogManager.Catalogs property

This property is defined in the type library as a property, it is accessed more like a method. It allows you to provide parameters for the search clause and other information for how the results should be returned.

 CatalogContext.GetCatalogs method (four overloads provided)

Getting the list of catalogs that should be available to a particular user using the CatalogSets functionality

ASP ASP.NET
CatalogSets.GetCatalogsForUser CommerceContext.Current.GetCatalogsForUser

This uses configuration data specified in the <profiles> section of the web.config file.

Searching for products or categories in a catalog or across catalogs (free-text or property-based)

ASP ASP.NET
CatalogManager.Search, specifying the catalog or list of catalogs to search. CatalogManager.Query and CatalogManager.FreeTextSearch methods are also provided, but Search is the preferred method. Use the CatalogSearch object, specifying either a comma-delimited list of catalogs to search by setting the CatalogNames property, or by providing a ReadOnlyStringCollection containing the catalog names to search by setting the CatalogNamesCollection property.

Searching a specific category for descendent products or categories

ASP ASP.NET
Category.Search Use the CatalogSearch object, setting both the catalog name and the category name. Set the Recursive property to true to search across all descendants, or to false to search only the immediate children of the category.

Refreshing cached catalog data

ASP ASP.NET
The catalog objects themselves do not cache any data. Use the CacheManager.RefreshCache method for each application-level cache that contains catalog data (see the files global_cache_lib.asp and BDRefresh.asp in the Solution Sites for example usage). The global_cache_lib.asp file is located in the <drive>:\Inetpub\wwwroot\<Solution Site>\include directory. The BDRefresh.asp file is located in the <drive>:\Inetpub\wwwroot\<Solution Site>\include directory. These files are only available if the Retail or Supplier Solution Site has been unpacked. Data for a subset of the Product Catalog System properties can be cached by the objects. To refresh this data, call the CatalogContext.Refresh method. You also need to refresh application-level caches that contain catalog data by accessing cache objects from the collection of site caches (CommerceContext.Current.Caches) and calling the Refresh method on each.

Setting the Product Catalog System to join catalog result sets against an external table

ASP ASP.NET
CatalogManager.SetJoinTable Use the <catalog> configuration section in the web.config file to specify this, or call the CatalogContext.SetJoinTable method explicitly at application startup.

Performing a specification search against a catalog

ASP ASP.NET
ProductCatalog.BeginSpecificationSearch, ProductCatalog.PerformSpecificationSearch, ProductCatalog.GuaranteedSpecificationSearch ProductCatalog.BeginSpecificationSearch, ProductCatalog.PerformSpecificationSearch, ProductCatalog.GuaranteedSpecificationSearch

Getting the list of properties that can be displayed on the site

ASP ASP.NET 
Set rs = CatalogManager.Properties
Rs.Filter(“DisplayOnSite=1”)
 This code sample describes how to cache the properties that can be displayed on the site. 
/*Get the properties in the catalog system*/
ReadOnlyStringCollection properties = CatalogContext.PropertyNames
DataSet ds;
/* For each property get the property attributes.*/
For each property
 Ds = CatalogContext.GetPropertyAttributes(propertyname)
/* Check if the DisplayOnSite attribute for that property is set to true and if so add it to the cache.*/
if ((bool)Ds.Tables[0].Rows[0][“DisplayOnSite”] == true)
/* Add property to a cache which can be used to display the properties.*/
  End if
End for

Setting the language on the catalog object

ASP ASP.NET
ProductCatalog.Language

This language will be inherited by the category and product objects created from the ProductCatalog object. When you get a ProductCatalog object from CatalogManager the ProductCatalog object will be set to the default language of the catalog.

 ProductCatalog.ActiveLanguage

This language will be inherited by the category and product objects created from the ProductCatalog object. When you get a ProductCatalog object from CatalogContext the ProductCatalog object will be set to the CurrentUICulture if the catalog supports this culture, otherwise, it will be set to the default language of the catalog.

Getting the list of properties in a catalog

ASP ASP.NET
CatalogManager.Properties(catalogname) ProductCatalog.PropertyNames

Accessing a product in a catalog

ASP ASP.NET
ProductCatalog.GetProduct ProductCatalog.GetProduct

Accessing a category in a catalog

ASP ASP.NET
ProductCatalog.GetCategory) ProductCatalog.GetCategory

Accessing the root category in a catalog

ASP ASP.NET
ProductCatalog.GetCategory(“”) ProductCatalog.GetCategory(“”)

Paging through a list of root categories

ASP ASP.NET
Not supported in the COM API ProductCatalog.GetRootCategories(searchOptions)

Paging through a list of root products

ASP ASP.NET
Not supported in the COM API ProductCatalog.GetRootProducts(searchOptions)

Getting the canonical path of a category to the root

ASP ASP.NET
Not supported in the COM API Category.CannonicalCategoryPath

Getting the canonical path of a product to the root

ASP ASP.NET
Not supported in the COM API Product.CannonicalCategoryPath

Ee798371.note(en-US,CS.20).gifNote

  • This property is expensive to compute. If this property is accessed frequently on a site, it is recommended that caching is enabled on the Product Catalog System objects. Caching is not enabled by default.

Getting the descendant products for a category

ASP ASP.NET
Category.DescendantProducts Category.GetProduct(searchoptions, fRecursive)

Getting the ancestor categories for a Product

ASP ASP.NET
The Product.AncestorCategories property returns a Recordset containing the ancestor categories. The Recordset also contains the display name for each ancestor category. The Product.AncestorCategoryNames property returns a ReadOnlyStringCollection containing the ancestor categories. To access the display name you will need to access the category properties.

Getting the parent categories for a Product

ASP ASP.NET
The Product.ParentCategories property returns a Recordset containing the parent categories. The Recordset also contains the display name for each parent category. The Product.ParentCategoryNames property returns a ReadOnlyStringCollection containing the parent categories. To access the display name you will need to access the category properties.

Getting the ancestor categories for a Category

ASP ASP.NET
The Category.AncestorCategories property returns a Recordset containing the ancestor categories. The Recordset also contains the display name for each ancestor category. The Category.AncestorCategoryNames property returns a ReadOnlyStringCollection containing the ancestor categories. To access the display name you will need to access the category properties.

Getting the parent categories for a Category

ASP ASP.NET
The Category.ParentCategories property returns a Recordset containing the parent categories. The Recordset also contains the display name for each parent category. The Category.ParentCategoryNames property returns a ReadOnlyStringCollection containing the parent categories. To access the display name you will need to access the category properties.

Getting the child categories for a Category

ASP ASP.NET
The Category.ChildCategories property returns a Recordset containing the child categories. The Recordset also contains the display name for each child category. The Category.ChildCategoryNames property returns a ReadOnlyStringCollection containing the child categories. To access the display name you will need to access the category properties.

The Category.GetChildCategories method returns a Dataset containing the child categories. The Dataset contains the display name for each child category. You can also pass search options to this method to page the results.

Copyright © 2005 Microsoft Corporation.
All rights reserved.