How to avoid the exception “Substitution controls cannot be used in cached User Controls or cached Master Pages.”

Recently I wrote example about using user controls with donut caching. Because cache substitutions are not allowed inside partially cached controls you may get the errorSubstitution controls cannot be used in cached User Controls or cached Master Pages when breaking this rule. In this posting I will introduce some strategies that help to avoid this error.

How Substitution control checks its location?

Substitution control uses the following check in its OnPreRender method.

protected internal override void OnPreRender(EventArgs e)
{
   
base
.OnPreRender(e);
   
for (Control control = this.Parent; control != null
;
            control = control.Parent)
    {
       
if (control is BasePartialCachingControl
)
        {
           
throw new HttpException(SR.GetString("Substitution_CannotBeInCachedControl"));
        }
    }
}

It traverses all the control tree up to top from its parent to find at least one control that is partially cached. If such control is found then exception is thrown.

Reusing the functionality

If you want to do something by yourself if your control may cause exception mentioned before you can use the same code. I modified the previously shown code to be method that can be easily moved to user controls base class if you have some. If you don’t you can use it in controls where you need this check.

protected bool IsInsidePartialCachingControl()
{
   
for (Control control = Parent; control != null
;
        control = control.Parent)
       
if (control is BasePartialCachingControl
)
           
return true
;

   
return false;
}

Now it is up to you how to handle the situation where your control with substitutions is child of some partially cache control. You can add here also some debug level output so you can see exactly what controls in control hierarchy are cached and cause problems.

Gunnar Peipman

Gunnar Peipman is ASP.NET, Azure and SharePoint fan, Estonian Microsoft user group leader, blogger, conference speaker, teacher, and tech maniac. Since 2008 he is Microsoft MVP specialized on ASP.NET.

    One thought on “How to avoid the exception “Substitution controls cannot be used in cached User Controls or cached Master Pages.”

    • June 18, 2012 at 5:39 am
      Permalink

      You are very right with that caching issue. Well, SharePoint has a suitolon for this for its own(!) library references.Call any SharePoint page, peek into the source code and search for the HTML script tags which load external Javascript files, e.g. init.debug.js or datepicker.debug.js . You will see that the SRC attributes have additional parameters like ?rev=4FrmHkiH0XlWZfpqgIaqEwxs to every link to Javascript files.Why? Because this is the trick’ so the client browser ALWAYS loads the newest version of the Javascript file from the server and not from the local browser cache!And now the trouble maker is, that YOU just have to do the exact same for your custom script links in your Ribbon definition, so that YOUR custom file is also fresh loaded from server and not from cache.But how??? No suitolon for this.

    Leave a Reply

    Your email address will not be published. Required fields are marked *