Weblog Ton Stegeman [MVP]

I was looking at the Redirect method in the SPUtility class. Besides the url, this method also takes a parameter of type SPRedirectFlags. I was wondering when to use the values of this enumeration. The MSDN documentation does help a bit, but not very much. I asked on Twitter if anyone knew the meaning of these values. Within minutes, Anders answered and pointed me in the right direction. One of the examples of why I love Twitter!

The signature of the Redirect method is:

public static bool Redirect(string url, SPRedirectFlags flags, HttpContext context)

• CheckUrl
• Default
• DoNotEncodeUrl
• DoNotEndResponse
• RelativeToLayoutsPage
• RelativeToLocalizedLayoutsPage
• Static
• Trusted
• UseSource

Source url

If UseSource is part of the flags parameter of the Redirect method, the url to which the user is redirected will be read from the querystring of the original request (context parameter). The new url will be the value of one of these querystring parameters:

• Source
• NextUsing
• NextPage

If one of these parameters has a value, the new url will be validated. Validation is done by the IsUrlSafeForRedirect method of the Request property of the current SPWeb. The url in the querystring of the original request needs to be a relative url. See the samples below.

If this url is not valid, or the UseSource parameter resulted in an empty string, the url parameter that was originally passed will be used.

Static url

If Static is part of the flags parameter, the url is considered relative. Depending on the presence of RelativeToLayoutsPage in the flags parameter, the url is relative to the ´_layouts´. If this enumeration value is present, SharePoint checks the flags parameter for the presence of RelativeToLocalizedLayoutsPage. If this is present, a new absolute url to the localized ‘_layouts’ folder is constructed. If not, the url is constructed to the root of the ‘_layouts’ folder. The layouts url is the url of the current SPWeb, followed by ‘_layouts’ and the Language of the current SPWeb. If constructing this url fails for whatever reason, the url will be the url of the current SPSite. If required, the value of SPGlobal.ServerCulture.LCID is added to the url.

Absolute url

If Static is NOT part of the flags parameter, the user will be redirected to the value of the url parameter, after validating the url. If Trusted is part of the flags parameter, the url is always valid. If Trusted is not available, it depends on the outcome of the IsUrlSafeForRedirect method of the Request property of the current SPWeb whether or not the url is valid.

Encoding

The last step is before the user is redirected is the encoding. If DoNotEncodeUrl is NOT present in the flags attribute, the url is first encoded using SPHttpUtility.UrlPathEncode.

Samples

Below you will find a number of samples. Each sample starts with the sample code for SPUtility.Redirect. This code is tested in a web part. The 3 lines below that sample show the results of calling the redirect. The first column contains the page url that contains the web part. The second column contains the result of the redirect.

SPUtility.Redirect(http://newsite, SPRedirectFlags.Default, HttpContext.Current);

SPUtility.Redirect("/news", SPRedirectFlags.Default, HttpContext.Current);

SPUtility.Redirect(http://newsite, SPRedirectFlags.Static, HttpContext.Current);

SPUtility.Redirect(http://newsite, SPRedirectFlags.UseSource, HttpContext.Current);

SPUtility.Redirect(http://newsite, SPRedirectFlags.UseSource | SPRedirectFlags.Trusted, HttpContext.Current);

SPUtility.Redirect(http://newsite, SPRedirectFlags.Trusted, HttpContext.Current);

SPUtility.Redirect("settings.aspx", SPRedirectFlags.Static | SPRedirectFlags.RelativeToLayoutsPage, HttpContext.Current);

SPUtility.Redirect("images/approve.gif", SPRedirectFlags.Static | SPRedirectFlags.RelativeToLayoutsPage | SPRedirectFlags.RelativeToLocalizedLayoutsPage, HttpContext.Current);