SPUtility.TransferToSuccessPage : Here is The Missing Documentation

Ok, so the SPUtility class is chock full of useful little doodads and widgets that try to make life easier for SharePoint developers. Actually, scratch that, it’s there to make life easier for the Microsoft team who develops SharePoint itself, but they’ve kindly let us have a bunch of public methods. One of the nifty features is the TransferToSuccessPage method and as you can see here, it’s very poorly documented. On top of that, it has some less than obvious behavior, so that lack of documentation is sometimes painful. There are millions of blog posts out there that touch on it, mention it, and complain about its lack of official documentation, so I won’t belabor that point; however, here’s the things you have to know when using it (specifically, the four string overload):


SPUtility.TransferToSuccessPage(message, nextUrl, linkText, linkUrl);


I typically use it like this

      
      SPUtility.TransferToSuccessPage(
                    "Successfully fooed your bar." +
                    " Click {0} to go back to the web root." + "
                    " Click Ok to proceed back to the list.",
                     someSPList.DefaultViewUrl
                        .Replace(Web.ServerRelativeUrl, 
                        string.Empty), 
                     "Here", 
                     Web.Url);


      // +s in the strings are for
      // your viewing pleasure, I don't 
      // usually do that
    

• The ‘nextUrl,’ which is where you go when you click ‘OK’ needs to be relative to the site (SPWeb) root, NOT the site collection root, and NOT the server root, and NOT full URL. You can see above I’ve taken a server-relative URL and stripped out the server relative URL of the site. This is because the ‘next url’ is crafted like this, (with the + operator) in the code:

  
currentSPContext.Web.Url + nextUrl;

  
  

• The {0} in the ‘message’ parameter is what is replaced by the generated link. It specifically creates an a-tag like this
  
<a href="{linkUrl}">{linkText}</a>

  You can specify a full URL, but if you specify a relative URL it will be relative to ~/_layouts/success.aspx. In case you didn’t notice, ~ is the WEB APPLICATION root. Not the site collection root. (They may be the same on your dev box, throwing some confusion your way when you go to production.) This is because SPUtility actually just straight up calls Server.Transfer(“~/_layouts/success.aspx”) which has no knowledge of SharePointyness like site collections and such.
  
  
• If you do not include a {0} in your message string, the last two parameters, linkText and linkUrl, are ignored (for all intents and purposes that is. Success.aspx still fiddles with them but it doesn’t affect your output)
  
  
• This will NOT work in a workflow or a SharePoint event handler because it requires an HttpContext, and those things don’t usually have one.
  
  
• Because it calls Server.Transfer, It WILL throw a first-chance ThreadAbortException so don’t call it from within a “catch-all” try block unless you plan to ignore the ThreadAbortException. See the MSDN Docs on Server.Transfer for info.
  
  

There you have it.