Refreshing Commerce Server Caches

	Introduction
	Commerce Server Caches
	Configuring Caches
	Using CacheManager
	The ProfileService Cache
	Refreshing Caches from the Business Desk

Introduction

This paper provides a conceptual overview of the caching architecture in Microsoft® Commerce Server 2000 and Microsoft Commerce Server 2002.

The following information is provided:

• Instructions for configuring Commerce Server caches so that the Publish and Refresh actions of the Commerce Server Business Desk modules function as expected.
  
• Detailed configuration information for performing cache refreshes for the Product Catalog System, campaigns data from the Targeting System, profile objects from the Profiling System, and tax and shipping rate data from the Order System.
  
• A description of the objects used for caching data in Commerce Server sites.
  
• Instructions for configuring your Commerce Server installation to ensure that the cache refresh capability is enabled.
  
• A description of how Business Desk uses the files BDRefresh.asp and RefreshApp.asp to signal the site.
  
• Instructions for configuring caches for sites based on the Retail Solution Site and for sites built using the Commerce Server .NET Application Framework.
  
• A description of how the Business Desk cache refresh, or Publish/Refresh functionality, is enabled, and a description of the mechanism used so that you can build custom tools with similar functionality.
  

Web site developers are the intended audience for this white paper, but system administrators may also find it useful. Most of the information in this paper applies to both Microsoft Commerce Server 2000 and Commerce Server 2002. Information pertaining to ASP.NET-based sites applies only to Commerce Server 2002.

Top of page

Commerce Server Caches

Microsoft Commerce Server Web servers cache business data when changes are made to that data. You can refresh caches in Business Desk for catalog data, campaigns data, profiles data, and transactions data.

Note: For Commerce Server, the words "refresh" and "publish" refer to the same function. The Commerce Server Business Desk Reports and Catalog Editor modules use "refresh." The Publish Campaigns, Publish Order Codes, and Publish Profiles modules use "publish."

Using Commerce Server Business Desk, you can refresh the caches that store product details from the Product Catalog System, campaigns data from the Targeting System, profile objects from the Profiling System, and tax and shipping rate data from the Order System. The next time Commerce Server receives a request for this data, the updated data is loaded in the caches. The ASP Solution Sites (Retail site and Supplier site) also cache rendered HTML fragments in a process referred to as fragment caching.

Note: Similar fragment caching capabilities exist in ASP.NET in the form of UserControl output caching; however, ASP.NET output caching is not covered in this paper, because it is not used in any of the Commerce Server Solution Sites. It is, however, an effective caching technique that is recommended to reduce latency and load on Commerce Server 2002 Web servers using ASP.NET.

Caching functionality is specific to a Web server. For example, in a Web farm that has two Web servers, each server has its own cache. If user information is load-balanced to a Web server on which the information is cached, the information is retrieved directly from the cache. If the information is not load-balanced, the information is retrieved from the database and is then stored in the Web server's cache.

When the specified size of a cache is filled in Least Recently Used (LRU) caches, new objects replace the object that was used the least recently (longest time ago).

Top of page

Configuring Caches

When you build sites based on the ASP Solution Sites, Commerce Server provides default configuration for the caches in your sites. However, if you create a site from scratch, you need to configure your own site caches. For an ASP.NET Site (in Commerce Server 2002), you define the cache configuration in the Web.config file. For a classic ASP site, you can define the cache configuration in the global.asa file (or in an Included file of global.asa). To define a cache, you specify the cache name, cache object, cache loader component and its configuration properties, and the cache writer component and its configuration properties.

Note: The cache writer component is optional.

The following tables list the ASP Solution Site caches (Retail site and Supplier site) and give details about the default configuration for each cache.

** Zero indicates that automatic cache refreshing is disabled for discounts. You should examine the requirements for running discount campaigns on your site and decide whether automatic refreshing of the discount cache is needed and how frequently it should occur. Discount events (for example, "Sold" events that occur when a discount is applied to a basket at checkout) are collected in the discounts cache and are not written back to the database until the next cache refresh occurs.

Note: The QueryCatalogInfo pipeline component uses QueryCatalogInfoCache, which is the most important catalog cache. Also, this cache is composed of raw data whereas the others are cache rendered HTML fragments (fragment caching).

Top of page

Using CacheManager

Each cache, with the exception of the profile object cache, uses the CacheManager component to manage the refresh policies of that cache. The Profiling System has its own built-in caching mechanism and does not use CacheManager.

CacheManager manages a collection of caches for a site. It is also a thread-safe component (registered as both-threaded in the COM registry), and is optimized for concurrent usage from all pages in your site.

Note: With a thread-safe component, many threads of execution can access the CacheManager simultaneously and perform concurrent operations on the caches without adversely impacting one another. Each time the cache manager is instantiated, a separate process context is created. The process is safe because the associated data is specific and private to that thread.

When you first access an ASP or ASP.NET page in a Commerce Server site, which causes the site to start running, the site framework creates a single instance of CacheManager, which is subsequently exposed to all pages in the site.

When you use the Commerce Server .NET Application Framework, you use the CommerceCache class instead of the CacheManager component. In Commerce Server 2002, this class wraps an internal instance of the CacheManager component. When the site begins running, the CommerceCacheModule class reads the caches element in the Web.config file to determine which caches to create and expose in a CommerceCacheCollection class.

When you install the Retail Solution Site, the CacheManager component is created and configured by code that runs in the Application_Start handler. This code can be found in the file global_cache_lib.asp in the Include directory. For more information, see "Include Files" in Commerce Server 2002 Help.

You can configure the RefreshInterval property of CacheManager to automatically refresh the cache with a specific number of seconds between cache refresh cycles. If you set the RefreshInterval property to zero for a cache, that setting disables automatic refresh cycles for that cache.

The RetryInterval property sets the time between retries after a cache refresh attempt fails. (For example, if the SQL resource that the cache refresh depends on is unavailable, the refresh operation fails and the CacheManager transitions to failure mode.)

You can call the RefreshCache method for CacheManager at any time to force an explicit refresh of the cache. You use this method to force an explicit refresh; otherwise refreshes are automatic. This method is synchronous and does not return until the cache refresh has completed or a failure occurs.

Top of page

The ProfileService Cache

The ProfileService cache differs from other caches because it does not use the CacheManager component. Instead, it includes its own built-in cache of profile objects. This cache cannot be disabled, although you can use a background thread created by ProfileService (enabled by default) to delete expired profile objects from the cache. There is no method to force a refresh of the Profiling System cache. The Retail Solution Site implements a refresh method that replaces the ProfileService instance with a new instance. When the old instance is released, all of the cached profile objects are released as well.

You control when the Profiling System refreshes and how often. You can configure the ProfileService cache using the following properties in the Profiling System connection string:

• PsObjectCacheSize. Use PsObjectCacheSize to configure the cache size (measured in number of profile objects). If you set this parameter to zero, the cache is not disabled; instead the cache is returned to its default size of 16,384 profile objects.
• PsBackgroundThread. Set PsBackgroundThread to 1 (enable) or 0 (disable) the background thread that cleans out the expired profile objects from the cache.
• PsObjectAgeoutPeriod. Use PsObjectAgeoutPeriod to set the length of time, in milliseconds, that an unreferenced profile object remains in the cache. The default value is 300,000 milliseconds (five minutes).

Although there is rarely a need to change these settings, you must add custom code to your site to do so. This code is used to retrieve the Profiles service connection string from the site configuration objects, append the appropriate properties, and use the modified connection string to initialize a ProfileService object (ASP) or ProfileContext object (ASP.NET).

In the Commerce Server Base Class Library, the ProfileContext class type corresponds to the COM ProfileService object.

Top of page

Refreshing Caches from the Business Desk

When you make changes in Commerce Server Business Desk (depending on your site configuration), you must refresh one or more caches on the site to reflect the changes you have made. For example, when you publish a catalog in Business Desk, a refresh message is sent to the Web server, which uses the CacheManager object to refresh the caches.

Note: When you stage your site in a test environment, changes are not reflected on the production site until the content is moved to the production site databases, and the caches on the production Web servers have been refreshed, either automatically or manually. (If the Web servers have not been refreshed, outdated information may be retrieved at run time.) This exception for test data applies to campaign and transaction configuration data, but not to profiles or orders data, which is rarely staged.

You can refresh caches in the following Commerce Server Business Desk modules:

• Catalog Editor
  
• Publish Campaigns
  
• Publish Profiles
  
• Publish Order Codes
  

When you publish or refresh data in Business Desk, the server application uses the Web-based Distributed Authoring and Versioning (WebDAV), using the ServerXMLHTTP object to access a specific ASP page in the Solution site application on the Web server. System administrators or business managers use this page to send a request to the Web server to refresh a cache or a set of caches. The page that is accessed on the site depends on the type of cache being refreshed.

Note: The ServerXMLHTTP object provides methods and properties for server-safe HTTP access between different Web servers. You can use this object to exchange XML data between different Web servers. For more information about the ServerXMLHTTP object see Frequently Asked Questions about ServerXMLHTTP at http://go.microsoft.com/fwlink/?LinkId=14189.

The pages accessed include:

• BDRefresh.asp. Refreshes all caches controlled by CacheManager. This page is coded to call the RefreshCache method to cause a refresh of a particular cache or set of caches, depending on the parameters in the QueryString.
• RefreshApp.asp. Refreshes the profiles resource. This page creates a new Profiles Service instance on your site so that all of the entries in the old cache are released.

In ASP.NET Sites, it is recommended that you use similarly named ASPX pages for the two files required for the refresh process, (for example, BDRefresh.aspx and RefreshApp.aspx). You can then code the ASP pages BDRefresh.asp and RefreshApp.asp to redirect to the corresponding ASPX page. The International Retail Site included with Commerce Server 2002 uses this method and provides an example of how to code these pages.

Securing the BDRefresh and RefreshApp pages

It is critical that you restrict access to the BDRefresh and RefreshApp pages to authorized personnel only using the Internet Information Services (IIS) file security feature. Restricting access to these pages mitigates the risk of denial of service attacks which use frequent refreshes of site caches. For more information about security, see "Securing BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp" in Commerce Server 2002 Help.

How Business Desk Locates the BDRefresh.asp and RefreshApp.asp Pages

When you refresh catalogs or publish campaigns in Commerce Server Business Desk, the Business Desk server application formulates a Uniform Resource Locator (URL). The URL must be accessed to request cache refreshes for each server and virtual directory on the site that hosts the cache. The Business Desk server then uses Web-based Distributed Authoring and Versioning (WebDAV), using the ServerXMLHttp object, to reference a page on your site that is coded to refresh caches. The pages accessed are BDRefresh.asp for all CacheManager caches and RefreshApp.asp for the Profiling System cache.

In a Web farm environment, the sever application sends this refresh request to all servers in the Web farm in order to keep the caches consistent across all of the Web servers. The Business Desk must be able to recognize a URL for each server hosting the site cache to be refreshed.

For profiles caches, the code to build the URLs that refer to the site RefreshApp.asp page for each server running a site is contained in the RefreshProfileSvcAll.asp page in the Profiles folder in the Business Desk server application. This code uses the GetAppsInSite method for the SiteConfigReadOnly object to obtain the list of Web server virtual directories for the site. For each virtual directory, the method creates a URL similar to the following URL:

“http://” + s_WebServerMachine + “:” + s_ServerBindings[1] + “/” +
 s_VirtualRootName 

In this example, s_WebServerMachine refers to the local NetBIOS computer name of the server and distinguishes the name so that it is unique from other servers in the Web farm. When you deploy Commerce Server, you must consider the following requirements:

• The Web Server virtual directories recorded in the Commerce Server administration database must be up-to-date and accurate.
  
• The URL is only valid if the Business Desk server can resolve the NetBIOS names of the Web servers; that is, the Web servers must be accessible from the local access network (LAN) on which the Business Desk server is running.
  

For CacheManager caches, the Web server automatically registers each virtual directory hosting a Commerce Server cache into a database table where the Business Desk server application can discover them. Cache loader components perform the auto-registration. CacheManager uses a provider model in which cache loader components (and optionally, cache writers) are configured for each cache. Cache loader and writer components implement the IPipelineComponent interface and optionally the IPipelineComponentAdmin interface for setting configuration properties.

Note: Though they implement IPipelineComponent, the cache loader components are not actually configured in or executed by a pipeline. They are executed directly by CacheManager.

When CacheManager refreshes a cache, it performs the following steps:

1. If a cache writer component is configured for the cache, the writer component is executed and the existing cache is passed by means of the Order parameter.

2. CacheManager creates a new cache object based on the CacheObjectProgID configuration property. (The default property is Commerce.Dictionary.) When the loader component is executed, the new cache object is passed by means of the Order parameter and the existing cache is passed by means of the Context parameter (except in the first refresh cycle, during which another empty cache object is passed for Context).

   If the CacheObjectProgID property is set to Commerce.Dictionary, then properties (including AppUrl) are passed to the loader component as name-value pairs in the cache dictionary. The loader component configures or populates the new cache object, or returns an HRESULT notifying the CacheManager that the old cache should continue to be used unchanged.

3. The loader component registers the cache in the appropriate Commerce Server database before it proceeds to configure or populate the new cache object.
4. The CacheManager performs an atomic pointer swap so that all new requests to GetCache will return the new cache object.

The following table lists the auto-registration tables used for each resource as well as the loader component used to perform the registration:

For the caches that use the LRUCacheFlush object as their loader component, the URL that is registered depends on the AppUrl configuration property that was configured in the dictionary specified by the LoaderConfig property. For all other CacheManager caches, the URL depends on the AppUrl property for CacheManager.

If the AppUrl property of CacheManager is not explicitly set, then CacheManager uses a built-in algorithm to determine the URL of the current site virtual directory. This algorithm uses the host name from the HTTP headers, therefore it is not reliable.

The CacheManager.AppUrl property is exposed by the .NET Base Class Library as the static property CommerceCache.ServerSpecificSiteUrl. Unfortunately, this property is read-only in Commerce Server 2002.

When the Business Desk Client Cannot Resolve Local NetBIOS Web Server Names

The Retail Solution Site sets both the CacheManager.AppUrl property and the LoaderConfig dictionary AppUrl property that is used by LRUCacheFlush to the value returned by the GetMachineBaseURL function.

In a typical installation of Commerce Server 2000 or Commerce Server 2002, the resolution of the local NetBIOS Web server name works for the Retail Solution Site. However, when you use a Business Desk server that is not able to resolve the NetBIOS name of the server, it is forced to use a Fully Qualified Domain Name (FQDN) or IP address. In this situation, set the AppUrl property to use a server-specific URL using the FQDN or the IP address for the server.

For example, the URL could be:

http://www1.example.microsoft.com/

As an alternative, you can modify the host file on the Business Desk server to contain an entry for each Web server that maps the NetBIOS name of the server to an FQDN.

For information about changing the value of GetMachineBaseURL in the Solution Sites, see the Microsoft Knowledge Base article, Changes Required When Catalog Refresh Done from BizDesk Using FQDN at http://go.microsoft.com/FWLink/?LinkId=12976.

Top of page