Sitecore 7.2 Upgrade Media Library Gotcha

EncodeNameReplacements Now Applies To Media Items

If you have spaces in your Media Library item names, this will be important to you.

While upgrading a client to Sitecore 7.2 this section of the release notes gave us pause:

Media API

When rendering media URLs, the system did not use the configuration in the encodeNameReplacements section to replace special characters in the URLs. This has been fixed so that media URLs also use the encodeNameReplacements configuration. (323105, 314977)

Summary: media library URLs now use the encodeNameReplacements configuration.

This will affect your Sitecore install if:

  • You are using encodeNameReplacements to replace whitespace in item names with hyphens in item URLs
  • And you have Media Library item names containing hyphens

This definitely applies to a few our instances. Mostly because the Media Library takes the original assets filename as the items name. Filenames are often formatted with hyphens.

The Fix

Option 1

Use Sitecore Powershell or something similar to execute code, removing all hyphens from Media Library names. For us this approach had the following drawbacks:

  • Media Library is very large
  • Media Library is not included in our standard production release
  • We don't run data migration code against production environments
  • Fragments atomicity of the upgrade
  • Regression testing to validate content authored links to Media Library content

Option 2

Replace Sitecore's MediaProvider with our own, removing the newly added encodeNamesReplacement functionality for Media Library items.

We're going with Option 2. It's the best option for us when accounting for timelines, stability and the drawbacks of our specific situation outlined in Option 1 listed above.

The Code

We're doing Option 2 which means we're using our own MediaProvider and removing the encodeNamesReplacement functionality.

All code for this patch is on GitHub under the Fishtank.MediaResolverPatch.

We have 3 files that we'll compile into one assembly:

File Description
FishtankMediaRequest.cs Removes decoding of media library assets, inherits MediaRequest
FishtankMediaProvider.cs New Media Provider reference in web.config, inherits MediaProvider
FishtankMediaConfig.cs Allows use of FishtankMediaRequest for decoding requests, inheritsMediaConfig

To use this, we'll find the mediaProvider section in the web.config and swap out the class and assembly. It's located at configuration > sitecore > mediaLibrary > mediaProvider.

         The media provider used to generate URLs, create media items, control media caching, parse media requests, and other
         media related functionality.      
      <!-- <mediaProvider type="Sitecore.Resources.Media.MediaProvider, Sitecore.Kernel"/>-- >
	  <mediaProvider type="Fishtank.MediaResolverPatch.FishtankMediaProvider, Fishtank.MediaResolverPatch" />


Now we've successfully reverted Sitecore 7.2 to resolve and render Media Library URLs as it did pre-upgrade. Again, all code is on GitHub.

We will keep Option 1 in our pocket as part of our next major-version Sitecore upgrade.

Thanks for reading. This article was authored using Markdown for Sitecore.

👋 Hey Sitecore Enthusiasts!

Sign up to our bi-weekly newsletter for a bite-sized curation of valuable insight from the Sitecore community.

What’s in it for you?

  • Stay up-to-date with the latest Sitecore news
  • New to Sitecore? Learn tips and tricks to help you navigate this powerful tool
  • Sitecore pro? Expand your skill set and discover troubleshooting tips
  • Browse open careers and opportunities
  • Get a chance to be featured in upcoming editions
  • Learn our secret handshake
  • And more!
Sitecore Snack a newsletter by Fishtank Consulting

Meet Dan Cruickshank


Dan is the founder of Fishtank. He's a multi-time Sitecore MVP and Coveo MVP award winner. Outside of technology, he is widely considered to be a top 3 father (routinely receiving "Father of the Year" accolades from his family) and past his prime on the basketball court.

Connect with Dan