Debugger "Feature" for SharePoint
While Windows SharePoint Services 3.0 provides an excellent platform for developing Web applications, debugging them can be a bit of a pain. It's often a case of finding the process ID (PID), attach the debugger, navigate to the error, rinse, and repeat, but programmers love to write code, not navigate through menus. J Fortunately, my good ol’ buddy from Microsoft Consulting Services and developer extraordinaire, Jonathan Dibble, created a nifty “Debugger Feature” that can be installed and activated on a SharePoint site to make the debugging experience much easier to initiate. Jonathan is a brilliant guy, but he’s too shy (for now) to engage the broad SharePoint community, so he has donated his code to Scot Hillier’s SharePoint Features project on CodePlex for all to share and hopefully extend. The blog entry below was jointly written by Jonathan and Scot.
<Lawrence />
Debugger Feature for SharePoint
When activated, the Debugger Feature adds an “Attach Debugger” menu item to the Site Actions menu (see picture below). The feature provisions a simple page, which executes the System.Diagnostics.Debugger.Launch statement, causing an exception to be thrown and the debugger to be auto-attached. In some cases, the debugger cannot attach – for example, when the AppPool is running under a different user account. When that happens, the page will at least give you the correct PID, so you can attach the debugger yourself.
Figure: Attaching the Debugger from SharePoint
Beyond this very basic and useful function, this is a great example of how to write a simple SharePoint feature that provisions a page. Included in the VS 2005 solution project are all of the .XML and .DDF files needed to create a feature and then a solution cab file for deployment. Let's take a quick walkthrough of the most important files.
The first .XML file, feature.xml, is what defines the feature:
<?xml version="1.0" encoding="utf-8" ?>
<Feature Id="B5CF5C33-8178-4cb0-99DC-E14AA04D1C05"
Title="Attach Debugger Feature"
Description="Can be used in debug mode to attach a debugger to the site."
Version="1.0.0.0"
Scope="Web"
xmlns="http://schemas.microsoft.com/sharepoint/">
<ElementManifests>
<ElementManifest Location="elements.xml" />
</ElementManifests>
</Feature>
The complete set of parameters can be found at http://msdn2.microsoft.com/en-us/library/ms436075.aspx. The critical element for us is the ElementManifest element, which specifies where WSS can find the provisioning instructions for our feature. The path is relative to the feature.xml, which in turn is relative to C:\Program Files\Common Files\Microsoft Shared\web server extensions\12. More on this when we construct our solution’s .CAB file. For now, know that the feature.xml and elements.xml are usually in the same directory.
Elements.xml:
<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<!-- Add Command to Site Actions Dropdown -->
<CustomAction Id="SiteActionsToolbar"
GroupId="SiteActions"
Location="Microsoft.SharePoint.StandardMenu"
Sequence="2001"
Title="Attach Debugger"
Description="Attaches debugger to current site">
<UrlAction Url="~site/_layouts/Debugger/AttachDebugger.aspx" />
</CustomAction>
</Elements>
Right now, the documentation on the contents of the elements file is fairly light. Looking briefly at our CustomAction element, the important attributes are the GroupId and Location, which tell WSS where to place our new page (the site actions standard menu). The Sequence number is for sorting the menu, 2001 should ensure we are at the bottom. And most importantly is UrlAction, which tells WSS that this will be a hyperlink to the AttachDebugger.aspx page. Notice the relative path token ~site, which indicates the page is located in our current site.
From here, I'd suggest opening the VS 2005 solution file and taking a look around. Notice how the directory layout inside the solution is similar to the layout in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE. This is also to facilitate feature development. Check out install.bat and see how we use xcopy to copy the dev tree to the template tree. (BTW, the commented lines in the install.bat should be obvious – we have no need to GAC our assembly or restart IIS for our feature, but you might in future features. It's there if you need them.)
Finally, lets look at how the .CAB file is created. The most important file is the .DDF file in the \WSP directory:
;
.OPTION EXPLICIT; Generate errors
.Set CabinetNameTemplate=DebuggerFeature.wsp
.set DiskDirectoryTemplate=CDROM ; All cabinets go in a single directory
.Set CompressionType=MSZIP;** All files are compressed in cabinet files
.Set UniqueFiles="ON"
.Set Cabinet=on
.Set DiskDirectory1=Package
manifest.xml manifest.xml
..\TEMPLATE\FEATURES\Debugger\feature.xml Debugger\feature.xml
..\TEMPLATE\FEATURES\Debugger\elements.xml Debugger\elements.xml
..\TEMPLATE\LAYOUTS\Debugger\AttachDebugger.aspx LAYOUTS\Debugger\AttachDebugger.aspx
It’s fairly easy to read, but take a look at the destination paths, which are relative to C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE. The location of the AttachDebugger.aspx file must match the TemplateFile Location path specified in the manifest.xml file:
<Solution SolutionId="3D615864-B200-4ff8-8D08-6D651CA9D5F6" xmlns="http://schemas.microsoft.com/sharepoint/">
<FeatureManifests>
<FeatureManifest Location="Debugger\feature.xml"/>
</FeatureManifests>
<TemplateFiles>
<TemplateFile Location="LAYOUTS\Debugger\AttachDebugger.aspx"/>
</TemplateFiles>
</Solution>
Once you've developed and deployed a feature or two, you'll have that light bulb (“a-ha!”) moment about how everything required to implement a feature relates to each other, and then you’ll want to create a SharePoint feature for every discreet piece of functionality that you’d like to add to SharePoint!
