SharePoint Thoughts - Discussion view

Debugging Web Parts - a full explanation of the requirements

Posted on 7/23/2004 3:41 PM by Maurice Prather

(7/24 update: minor changes to the original article, copy/paste mistakes corrected)

Brilliant minds think alike… :)

Yesterday afternoon, I thought that the next topic for the blog should be about building and debugging web parts. Looks like Daniel McPherson was on the very same wavelength (see http://blogs.msdn.com/danielmcpherson/archive/2004/07/23/192496.aspx). Since he has already knocked out the building part of the discussion, invariably the next question is “How do I debug web parts?”

For the most part, debugging web part assemblies is not difficult. It just requires a little knowledge of what you’d like to accomplish.

First the basics…

Setting CallStack=true
By default, WSS will redirect a user to the error page whenever an unhandled exception is encountered during the render cycle. To disable this behavior, open your web.config and set CallStack="true" in the <SafeMode> node. This allows you to see a typical Asp.net error page.

Setting customErrors mode…
The next step would be set mode=”Off” in the <customErrors> node. This instructs Asp.net to show you a complete error report rather than a generic “Server Error” page.

Now for the advanced stuff…

Too many times, I’ve seen folks improperly state that you must set the <compilation> debug=”true” in order to debug web part assemblies. This is WRONG.

In that same note, folks also improperly state that you must set <trust> level=”Full”. This too is WRONG.

It all depends on a) what you are trying to do and b) what you want to debug.

If you take care of the very first two basic items, you are ready to debug your web part assemblies. If you want advanced behaviors you will need to consider how these two properties interact with each other.

Why set debug="true"?
In a vanilla Asp.net world, setting the debug attribute of the <compilation> node to “true” instructs Asp.net to generate pdbs when compiling pages.

Now consider two facts:

Web Parts must live in precompiled assemblies.
Chances are 50/50 you’re attempting to debug web parts on an unghosted page; therefore, you’re under the jurisdication of the SafeMode parser, which we know doesn’t compile pages. Please refer to the Ghosted/Unghosted pages discussion for more information - http://www.bluedoglimited.com/SharePointThoughts/ViewPost.aspx?ID=4.

As you can start to see, unless you’re attempting to debug inline code contained within a ghosted page, there is no need to tell Asp.net to generate pdbs. When you create/install your web part assembly, you can just as easily create/install the necessary pdbs. Thus, setting debug=”true” is not necessary for general debugging. There is one exception to this rule…

So, when would I set debug=true?
Set this value to true if you want Visual Studio to auto-attach to the process. In other words, when you press F5 (equivalent to Debug|Start) Visual Studio launches IE and attaches to the corresponding server process.

Ok… I set debug=true, but now VS tells me “Error while trying to run project: Unable to start debugging on the web server. The project is not configured to be debugged.”
Now this is where folks really go astray. Asp.net will only generate pdbs if a web application has been granted the appropriate AspNetHostingPermission.Level permission (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwebaspnethostingpermissionclasstopic.asp).

By default, WSS operates with the trust level set to WSS_Minimal. The WSS_Minimal policy grantes AspNetHostingPermission.Level=Minimal, which does not meet the permission requirement for generating pdbs. Asp.net demands AspNetHostingPermission Level=Medium or greater. Therefore, you will receive a message of "System.Web.HttpException: Debugging is not supported under current trust level settings."

Note: Reference the “Microsoft Windows SharePoint Services and Code Access Security” whitepaper for more information on WSS_Minimal, etc (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odc_sp2003_ta/html/sharepoint_wsscodeaccesssecurity.asp).

Unfortunately, too many people don’t know this or don’t care and hence they tell others to set the trust level to Full when setting debug="true". Although this works, this is not a true requirement.

Your options are…

Selectively raise the AspNetHostingPermission Level in your current policy file to Medium.
Raise the entire trust level from WSS_Minimal to Medium/WSS_Medium or greater. Yes, granting Full trust is effectively the same, but it is massive overkill.

More importantly, if you’re trying to track down problems associated with code access security, setting the trust level to a higher state simply hides the very same problems you were attempting track down.

What if I am chasing down code access security issues?
Ask yourself this… do I want to auto-attach to the process? If yes, then you need to adjust the security policy so that at least AspNetHostingPermission.Level=Medium is granted (again, be aware that you’ll be operating with higher permissions). Otherwise, the simple answer is to manually attach to the process. Manual attachment does not require you to change the debug or trust settings.

Quick summary:

Only two property settings need to be adjusted to display “debug” data in the browser.
Set debug=true only when...

attempting to debug inline server-side code
you want Visual Studio to auto-attach to the w3wp process

Setting the trust level to Full is overkill and hides code access security problems.
Manually attaching to a process offers the “least impact”.