Breaking Change

GOTCHA: Change to Media Library URLs /  by Derek Hunziker

If the following items apply to you, you'll want to read this post carefully before proceeding with an upgrade.

  1. You are thinking about upgrading to Sitecore v7.2+
  2. You have hyphens in your Media Library item names
  3. You use <replace mode="on" find=" " replaceWith="-" /> to achieve SEO-friendly URL

Sitecore introduced a change to the way Media Library item URLs are handled in Sitecore v7.2+. If you happen to be using the encodeNameReplacements configuration to replace spaces with hyphens in your URLs (a very common practice, from my experience), then you have some decisions to make.

In a nutshell, Media Library items now adhere to the encodeNameReplacements settings, whereas, before Sitecore v7.2, they did not. This setting controls which characters in an item's name get replaced in the URL—allowing you to achieve SEO-friendly URLs with just a few lines of configuration. However, in order to resolve items and serve up content, Sitecore essentially applies the replacements in reverse to locate the Sitecore item in the tree. As a result, if you have any items in your Media Library that contain a hyphen in their name, Sitecore will be unable to resolve the request to that item, and you'll get a 404 instead.

Say, for example, you have a media item named: My Super-snazzy Image. 

Prior to Sitecore v7.2, this would result in the following URL:

/~/media/My%20Super-snazzy%20Image.ashx

However, in v7.2+, with the encodeNameReplacements settings in place, this URL will become:

/~/media/My-Super-snazzy-Image.ashx

The trouble with the later URL is that Sitecore will apply the replacements in reverse, and will attempt to find an image with the name of My Super snazzy Image (which does not exist!).

There are several options for dealing with this issue:

  1. Replace all hyphens with spaces in media library item names (see PowerShell Scripts for an example)
  2. Apply the official Sitecore patch to permit hyphens in Media Library names. This also requires that you do not mix both hyphens and spaces in the item name or any part of a path, so some renaming may still be necessary.
  3. Restore the pre-7.2 behavior using a solution such as this.
  4. Remove the encodeNameReplacements setting. This approach is less desirable as it can break existing URLs and allows URLs that are not SEO-friendly.

No matter which option is chosen, it is often a good practice to enforce consistent item names using the rules engine or by correcting the names automatically in the item:saving Sitecore event.