Media Options and Query String Parameters in the Sitecore ASP.NET CMS

This blog post lists the query string parameters used in URLs of media items in the Sitecore ASP.NET CMS.

The Presentation Component Reference manual on the Sitecore Developer Network (SDN) lists parameters that you can pass to the <sc:image> XSL control, which renders the HTML markup to display the image referenced in a field of type Image. Sitecore adds corresponding parameters to the query string of the URL for the media item.

Some of these query string parameters affect image aspects, such as sizing. Others apply to any type of media, such as language, version, database, and cache functionality.

Here is a list of the supported query string parameters:

  • w: Width in pixels
  • h: Height in pixels
  • mw: Maximum width in pixels
  • mh: Maximum height in pixels
  • la: Language (defaults to context language)
  • vs: Version (defaults to latest version)
  • db: Database name (defaults to context database)
  • bc: Background color (defaults to black)
  • as: Allow stretch (as=1)
  • sc: Scale by floating point number (sc=.25 = 25%)
  • thn: Thumbnail (thn=1)
  • dmc: Disable media caching, both retrieval and storage (dmc=1)

In general, avoid constructing URLs using these query string parameters explicitly. For example, use the Sitecore.Data.Items.Item.Appearance.Icon property to retrieve the icon, the Sitecore.Resources.Media.MediaManager.GetThumbnailUrl() method to retrieve the URL, or the Sitecore.Resources.Media.MediaManager.GetMediaUrl() method with the Sitecore.Resources.Media.MediaUrlOptions class to construct the URL programatically. Remember to use something like the Sitecore.StringUtil.EnsurePrefix() method to ensure that media URLs begin with a slash (/) rather than a tilde (~). Media URLs that begin with this character can result in multiple URLs for media items and sooner exceed IIS path length limits. You can download some sample code that shows these techniques.