Cacheable Portlet

From Sense/Net Wiki
Jump to: navigation, search
  •  
  •  
  •  
  •  
  • 100%
  • 6.0
  • Enterprise
  • Community
  • Planned

Overview

Portlet
A Cacheable Portlet is a portlet type that leverages caching functionality. A portlet is cacheable if it inherits from the cacheable portlet base type. When a portlet is cacheable a Cache tab appears on its portlet property dialog where caching can be switched on and off and cache parameters can be set.

Details

Some portlets support caching functionality. When a portlet is Cacheable a Cache tab will appear on the portlet properties dialog. When caching is enabled the portlet will cache its output for the given interval and thus when rendered no background logic will be executed within the cache interval. With this technique page response time can be lowered significantly.

It is strongly advised to use the cache functionality of portlets when available on live sites. Portlets that are not being cached may cause pages to be less responsive even at small visitor rates.

Cache is only enabled for visitors and logged in users that are not member of special kind of content administrator groups. These groups are enumerated in the web.config under the "AdminGroupPathsForLoggedInUserCache" appsetting key! This is an important notice when creating sites with large number of content administrator users.

Parameters

The following parameters are available to enable cache functionality (for visitors):

  • Portlet is cached: enable cache by checking this box. By default (application) page path and portlet client id are used as cache key.
  • Portlet is cached for logged in user: enable cache for logged in users by checking this box. If checked (and portlet caching is enabled above) portlet output will be preserved even if users log in to the portal. It is possible to provide exceptions as a group path list in configuration - users in these groups (e.g. Administrators) will always get the real-time value. Default value is true.
  • Request host influences caching: defines whether the request's URL-host (e.g. 'example.com') is also included in the cache key. When unchecked portlet output is preserved regardless of the host that the users use to browse the site.
  • Request path influences caching: defines whether the requested content path is included in the cache key. When unchecked portlet output is preserved regardless of the page's current context content or request path. Check it if you want to cache portlet output depending on the requested context content.
  • Url query params influence caching: when left unchecked portlet output is preserved regardless of changing url params - otherwise url query params are also included in the cache key for the portlet and thus cached portlet output will depend on url query parameters. For example a portlet on a page will be cached for the requests with ?param=1 query parameter independently of the caching for the requests with ?param2=2 param.
  • Language influences caching: Defines whether the language code is also included in the cache key. When unchecked portlet output is preserved regardless of the language that the users use to browse the site. If set, a different output will be cached for any language the users visit the site on.
  • Sliding expiration: sliding timeframe in seconds. The portlet is refreshed when it has not been accessed for the given seconds.
  • Absolute expiration: gives refresh periodicity in seconds. The portlet will be refreshed periodically with the given time period.
  • Custom cache key: defines a custom cache key independent of requested path, page path and query params. Useful when the same static output is rendered at various pages. For example giving mycachekey to two different portlets placed on two separate pages will result in the two portlets having the same cached output expiring at the same time. In this case Sliding expiration and Absolute expiration also have to be set to the same values in all portlets using the same custom cache key, so that expiration settings do not depend on the portlet instance that has been accessed first.
  • Debug: when checked debug info about portlet cache state is shown at the bottom of the portlet's layout.

Sliding and Absolute expiration

  • If you intend the portlet output to expire at a specific time after it has been accessed, you set the Absolute expiration parameter to the specific time, and the Sliding expiration parameter to 0.
  • If you intend the portlet output to expire after a certain amount of time has passed since the last access to the item, you set the Sliding expiration parameter to the expiration interval, and the Absolute expiration parameter to 0.
  • If you set both parameters to any number different from 0 the Sliding expiration parameter is neglected and taken as if it was set to 0.
  • If Absolute expiration is set to -1, it comes from the value of AbsoluteExpirationSeconds key in Web.config.
  • If Sliding expiration is set to -1, it comes from the value of SlidingExpirationSeconds key in Web.config.

Default settings

  • Portlet is cached: By default caching is enabled for the following portlets:
  • Portlet is cached for logged in users: by default this is set to true but only takes effect if general portlet cache is enabled.
  • Request host influences caching: default is false.
  • Request path influences caching: default is true.
  • Url query params influence caching: For the Content collection portlet this property is set to true by default so that views that use paging also work properly (since paging uses url query params to identify the current page of content collection to be presented).
  • Absolute expiration: default is -1 (comes from web.config, where default setting is 120).
  • Sliding expiration: default is -1, (comes from web.config, where default setting is 0).

Please note, that if both Absolute expiration and Sliding expiration value is set to 0, the expiration duration will be infinite. So the proper way to set cache expiration to zero is to turn off cache functionality by unchecking the Portlet is cached option.

Debugging

Working with portlets having cached output can be quite confusing in development time. The following features can be very helpful when debugging cacheable portlets:

  • ?disablecache=true: use this url query parameter to switch of portlet caching for the whole page. When this parameter is given portlets on the current page will render their output according to the normal workflow, as if they weren't cached.
  • Debug: set this portlet property to true to display cache information at the bottom of the portlet layout, for example:
Portlet info: fragment has been retrieved from Cache. Cache key: EYeIAH0nuHjU6toSaZcOyhBg+pg=
  • ?showexecutiontime=true: using this url query parameter will let the page display execution time info for every portlet. Info will be displayed green if the portlet output is being cached, and red if not.

for Developers

To create a portlet that utilizes caching functionality inherit your portlet from the CacheablePortlet base type. Please note the return condition at the beginning of the CreateChildControls function.

It is strongly advised to always develop cacheable portlets. Cacheing can be switched off on cacheable portlets any time, but the only way to make non-cacheable portlets cacheable is to rewrite them.

    public class MyPortlet : CacheablePortlet
    {
        protected override void CreateChildControls()
        {
            if (Cacheable && CanCache && IsInCache)
                return;
 
            // your code comes here
        }
    }

The conditional return command checks the following:

  • Cacheable: caching has been switched on at the portlet property page.
  • CanCache: portlet output is allowed to be cached - ie. current user is visitor and not logged in user.
  • IsInCache: portlet output has formerly been put into cache.

Please note that when a portlet is cached it's output is rendered regardless of the portlet's background logic. It is highly recommended to check if the portlet is in cached state in the first line of any control events / methods, otherwise implemented background logic will be executed totally unnecessarily and lengthy operations may cause performance issues even though the portlet output is being cached!

Sometimes it is useful to inherit from a portlet that already uses caching functionality. But what if we want to switch off caching functionality in a child class that inherits from a cacheable portlet? Put the following lines in the constructor of your portlet, and this will make the Cache tab disappear and also switch off caching:

   public MyPortlet() 
   {
      this.HiddenPropertyCategories = new List<string>() { EditorCategory.Cache };
      this.Cacheable = false;   // by default, caching is switched off
   }

Example/Tutorials

The following tables summarize how caching works for portlets placed on different pages. Letters (A,B,C,D,E) indicate that Single content Portlets put out to the pages below use identical or different cache keys and therefore render the same or different output.


  • Custom cache key: mycustomcachekey
  • Request path influences caching: don't care
  • Url query params influence caching: don't care
Identical output for cached portlets
Identical output Requested url Cache key
A http://localhost/NewsDemo/External/Gitex?action=Edit DC6+d/b9SxmeycLcW1M2rAs7y4U=
A http://localhost/NewsDemo/External/Gitex?action=Browse DC6+d/b9SxmeycLcW1M2rAs7y4U=
A http://localhost/NewsDemo/External/Join_us?action=Edit DC6+d/b9SxmeycLcW1M2rAs7y4U=
A http://localhost/NewsDemo/External/Join_us?action=Browse DC6+d/b9SxmeycLcW1M2rAs7y4U=
A http://localhost/NewsDemo/External/Join_us?action=Browse&hello=12 DC6+d/b9SxmeycLcW1M2rAs7y4U=

  • Custom cache key: ""
  • Request path influences caching: 0
  • Url query params influence caching: 0
Identical output for cached portlets
Identical output Requested url Cache key
A http://localhost/NewsDemo/External/Gitex?action=Edit AdZNhN8h2bpP25sch0bXpI3Xxcg=
B http://localhost/NewsDemo/External/Gitex?action=Browse DTA58/8itGbzJ5aTTDorS5o/Zl4=
A http://localhost/NewsDemo/External/Join_us?action=Edit AdZNhN8h2bpP25sch0bXpI3Xxcg=
B http://localhost/NewsDemo/External/Join_us?action=Browse DTA58/8itGbzJ5aTTDorS5o/Zl4=
B http://localhost/NewsDemo/External/Join_us?action=Browse&hello=12 DTA58/8itGbzJ5aTTDorS5o/Zl4=

  • Custom cache key: ""
  • Request path influences caching: 1
  • Url query params influence caching: 0
Identical output for cached portlets
Identical output Requested url Cache key
A http://localhost/NewsDemo/External/Gitex?action=Edit 9xpQG4++fk4TYK+BZsf1JYAh+ic=
B http://localhost/NewsDemo/External/Gitex?action=Browse 4Hy9rl2j+JUoEc92hQgNJWJTXTA=
C http://localhost/NewsDemo/External/Join_us?action=Edit ekpJf/3EX/tPpsSwR1/DqlIclr4=
D http://localhost/NewsDemo/External/Join_us?action=Browse IMIzvS3IkjralhL+v2kZnwFjT1o=
D http://localhost/NewsDemo/External/Join_us?action=Browse&hello=12 IMIzvS3IkjralhL+v2kZnwFjT1o=

  • Custom cache key: ""
  • Request path influences caching: 1
  • Url query params influence caching: 1
Identical output for cached portlets
Identical output Requested url Cache key
A http://localhost/NewsDemo/External/Gitex?action=Edit /ciScmIhhJRb1tWRmUzPi0AwVIk=
B http://localhost/NewsDemo/External/Gitex?action=Browse hCdXkRVUxdl6KZ4yfycRdE8XnTc=
C http://localhost/NewsDemo/External/Join_us?action=Edit IGY8iAyyaz9bPz9I2c3bFS+C+Nc=
D http://localhost/NewsDemo/External/Join_us?action=Browse 8f8NBK4en3izhXTVlUFT2okXhUI=
E http://localhost/NewsDemo/External/Join_us?action=Browse&hello=12 skjtHsbgY6g71rMX8KvgVYkBQbs=

  • Custom cache key: ""
  • Request path influences caching: 0
  • Url query params influence caching: 1
Identical output for cached portlets
Identical output Requested url Cache key
A http://localhost/NewsDemo/External/Gitex?action=Edit 3YDZYziCzlM4Z0U3nQUuFEWQZIA=
B http://localhost/NewsDemo/External/Gitex?action=Browse Akq16F6VSPrR+DuY7H+AZyIzr+Q=
A http://localhost/NewsDemo/External/Join_us?action=Edit 3YDZYziCzlM4Z0U3nQUuFEWQZIA=
B http://localhost/NewsDemo/External/Join_us?action=Browse Akq16F6VSPrR+DuY7H+AZyIzr+Q=
C http://localhost/NewsDemo/External/Join_us?action=Browse&hello=12 43vE0nRhrq0oxS+TqPe7C0RxlmY=

Related links

References