Development is the first part
to create an application, but when there are issues with the code,
having an easy way to debug the code and determine the issues is
critical. Visual Studio and SharePoint provide the tools needed to do
this during the development of the code as well as after the code has
been deployed to a production site. The major changes for this release
are around debugging SharePoint apps and the authentication needed to
debug code running on remote servers. The Developer Dashboard has been
given a makeover and now provides integrated debugging with logging
output.
1. F5 Debugging
The standard for debugging in Visual Studio is called F5 Debugging
after the shortcut key to start the debugger and attach the code to the
running process. Visual Studio added F5 Debugging to the previous
version of SharePoint for the classic SharePoint Solutions, and now
that same feature can be used with SharePoint apps.
SharePoint Applications
Debugging apps for SharePoint requires
a few more authentication handshakes than the classic SharePoint
Solutions due to the architecture. Luckily Microsoft has made pressing
F5 just as simple as it is for the classic SharePoint Solutions. By
default, Visual Studio uses IIS Express as the localhost for debugging
sessions. The IIS Express application is a portable version of IIS that
does not need to be installed prior to running it. If there is
interaction with the remote app and host web, you may be promoted to
grant permissions prior to debugging. To debug the app for SharePoint,
you need to be connected to SharePoint Developer Site and allow the
application to be trusted if needed. If you are not, you will see an
error like the one shown in Figure 1.
Following are the steps performed by Visual Studio when you press F5:
1. It builds the Web Application Project if needed.
2. It changes the URLs in the AppManifest.xml and other project files.
3. It packages only the SharePoint-specific artifacts into the Open Package Convention (OPC).
4. It uninstalls the SharePoint App.
5. It installs the SharePoint App (OPC) using the life cycle API.
6. It updates the Hosts file if Peer Name Resolution Protocol (PNRP) is not used.
7. It launches the Web Application Project in IIS or IIS Express if there is one.
8. It updates the web.config with the correct client ID.
9. If the
LaunchUrl in the App manifest is set to a site page in the App Project,
then launch the browser to the LaunchUrl. If not, Visual Studio just
launches the All apps page.
10. Visual Studio attaches the script debugger or Silverlight debugger.
The debugging experience will be familiar to any
ASP.NET developer with the web application projects. Because there may
be a large portion of the code in JavaScript, it is nice to have the
script debugger automatically attached and ready. The experience with
the SharePoint-hosted apps contains more files to work through because
all the JavaScript files will be loaded from the SharePoint page. A
good strategy for quickly building your app would be to develop any of
the Web Application components that do not rely on other frameworks
first and then add the dynamic functionality after you have the code
ready to go. It is a great debugging experience as long as the
development environment and server locations are correctly configured.
Make sure to do the preplanning to set up your environment, and you can
quickly build powerful apps and debug them by simply using F5.
Classic SharePoint Solutions
Using Classic SharePoint Solutions, you
can allow debugging support by setting a breakpoint and starting the
debugger by pressing F5. The same experience is provided if you select
the Farm or Sandbox solution from the Visual Studio projects. The first
time you debug a SharePoint solution in Visual Studio, you will be
asked to automatically configure your web.config on the SharePoint
server to support the debugging sessions. This is done to prevent the
need for manual changes to the server for every development
environment. Also, this helps reduce the mistakes and frustration of
not remembering every change needed to begin debugging. These steps
also include recycling the app pool, retracting the solutions,
deploying the solution, and activating the required features. This
entire behavior can be modified from the Visual Studio properties and
editors.
NOTE You
need administrative permissions to the server to change web.config from
Visual Studio, and these changes should not be done on a production
server.
Visual Studio takes three steps on your behalf.
First, it turns on the call stack in the web.config by adding the line
CallStack=true. Second, it disables custom errors in ASP.NET so that
you receive detailed error information if there is an error, using <customErrors mode="Off"/>
in your system.web section. Lastly, Visual Studio enables complication
debugging, which makes ASP.NET compile your binaries with additional
information to make debugging easier using <compilation debug="true"/>.
Besides making these changes, Visual Studio
performs a number of steps when you start the debugging session from
deployment to attaching the debugger as follows:
1. It runs your predeployment commands that you can customize.
2. It creates your WSP using MSBuild places in the bin\<build> directory.
3. If you deploy to the farm, Visual Studio recycles the IIS application pool to free resources.
4. If you
deploy a new version of an existing solution, it deactivates your
feature, uninstalls your existing solution, and deletes the existing
solution package on the server. If you have feature receivers, your
code will be executed.
5. It installs your new solution and features onto the server.
6. If you build a workflow, Visual Studio installs your workflow assemblies.
7. It
activates your Site or Web features. You need to activate Web
Application or Farm features. Again, the feature receivers will be
executed to run the code.
8. For workflows, Visual Studio associates your workflow with the list or library you selected in the Workflow Wizard.
9. It runs your post-deployment commands.
10. It
attaches the debugger to the SharePoint process (w3sp.exe) for Full
Trust solutions and to the SPUCSPUWorkerProcess.exe for Sandbox
Solutions.
11. If you deploy to the farm, Visual Studio starts the JavaScript debugger.
12. Visual Studio launches your browser and displays the correct SharePoint site for your solution.
A few notes about these steps. First, if you
debug a workflow, you need to trigger the workflow through the web
browser, the client applications, or custom code that you have written.
Visual Studio doesn’t automatically trigger your workflow. Also for
workflows, any additional assemblies you reference must be in the
global assembly cache (GAC).
Second, if you work with feature event receivers,
don’t have Visual Studio activate that feature event receiver for you.
Instead, manually activate your feature event receiver so that it is in
the same process as the debugger. You can disable activation in your
deployment in your project settings.
Because SharePoint builds on many layers below
it, such as Windows Communications Framework (WCF), you may want to
enable advanced debugging in your Visual Studio environment. To do
this, go into the Registry Editor, find [HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\SharePointTools], and change the DWORD value for EnableDiagnostics from 0 to 1. If the DWORD value does not exist, create it as a new DWORD
value. When you set this value, you see in the output window in the
Visual Studio all the information that Visual Studio gets form
SharePoint via the stack trace.
2. Debugging Using the Developer Dashboard
The Developer Dashboard has become a
must-have tool for any user of SharePoint. A total redesign of the
Developer Dashboard was required to make it easier to use and to
provide better performance. Now the Developer Dashboard is not just for
developers but can be used by IT professionals because of the
diagnostic information provided from the dashboard. The main use of the
Developer Dashboard still remains to provide diagnostic information for
the page that is rendered. The information can range from basic page
information to the ULS logs associated with the page. One of the major
changes is how the Developer Dashboard displays and how it gathers the
information. Figure 2 shows the Developer Dashboard and its components.
A number of tabs can now provide more detailed
information about each request, and all the information is not in a
single page. The trace information provides more information when
available, such as the SQL tab, which enables you to click any request
to see the detailed SQL command and analytics on each call. Also, you
can see the ULS logs for the correlation ID for the page directly from
the browser. The data that populates the browser pop-up window comes
from a dedicated WCF service named diagnosticsdata.svc. This service was designed specifically for the Developer Dashboard and provides tracing information.
NOTE Diagnostic data is dependent on the Usage and Health Data Collection Service Application, which must be created and running.
By default, the Developer Dashboard is off but
allows a few options to turn it on. In the previous version of
SharePoint, you could select three options, but SharePoint 2013 has
only two modes, which are on or off. The On option is now equivalent to
the On Demand option that places the icon on the page. The reason that
there are only two options now is because the control is not embedded
in the page, which means you don’t need to worry about the control
affecting content on the page. To enable the Developer Dashboard from
PowerShell, you can use the following lines of script; just make sure
to turn it off when you finish using it in production:
$contentService = ([Microsoft.SharePoint.Administration.SPWebService]::
ContentService)
$devDashboardSettings =$contentService .DeveloperDashboardSettings
$devDashboardSettings.DisplayLevel =
[Microsoft.SharePoint.Administration.SPDeveloperDashboardLevel]::On
$devDashboardSettings.Update()
This same script could be written in code because
the PowerShell script and code use the same set of APIs. This depends
on the usage you need to turn on the Developer Dashboard. For example,
you might turn on the Developer Dashboard anytime you throw an
exception in your code but turn it off on any other page render. As you
can see, you need to add a reference and Using statement to
Microsoft.SharePoint.Administration in your code. The code also needs
to be run with the correct security context because the Developer
Dashboard is a farm-wide setting.
3. Debugging Using SharePoint Logs
With the changes to the Developer
Dashboard, you no longer need to go to the Unified Logging System (ULS)
for a page. However, if you have other SharePoint Solutions or need to
understand other actions happening at the same time as a page render,
you still must use the SharePoint logs. The ULS logs contain logging
information about actions that happen within SharePoint, so you might
not see any logs related to the new apps for SharePoint. If you write
apps hosted in SharePoint, you could still take advantage of logging to
the ULS. Although, you could browse the ULS logs, using your favorite
text editor. One great tool to check out is the ULSViewer, which is a
free download from MSDN at http://code.msdn.microsoft.com/ULSViewer.
It is an unsupported tool, but it is good at parsing the ULS logs and
provides real-time viewing, smart highlighting (in which it highlights
similar log entries when you hover over them), and a number of other
features.
4. Debugging Silverlight Code
Visual Studio enables script debugging
by default. If you want to debug a Silverlight application that runs in
SharePoint, you need to change the properties under your project in the
SharePoint section to check the Enable Silverlight Debugging check box.
Silverlight does not allow cross-domain scripting
by default. If you make calls across domains, such as copying from one
SharePoint site to another that may be in a different farm or uses a
different URL, you need to become familiar with the clientaccesspolicy.xml
file that you can use with Silverlight to override this policy. This
will become common for developers building apps and including
Silverlight on the web pages. You must place this file in the root of
your SharePoint web server in the filesystem so that Silverlight has
access to the new policy file.
5. Other Useful Tools for Debugging and Testing
Many community members have built tools
for SharePoint since SharePoint 2007. Although these tools have not
always been upgraded, many of the APIs in SharePoint have not changed,
which means the tools may still work. Beyond Visual Studio, other
useful tools can help you with debugging and testing in SharePoint.
SPDisposeCheck
One of the primary tools used for
classic SharePoint solutions has been SPDisposeCheck. This tool enables
scanning of code to determine if there are any memory leaks based on
known patterns. The SharePoint APIs allocate COM-based memory that the
Common Language Runtime (CLR) garbage collector does not release. For
this reason, you need to explicitly call the Dispose() method on certain objects such as the SPSite and SPWeb
objects. If you don’t dispose of them, you get memory leaks in your
application, and it can be hard to track down which pieces of your code
are causing the leaks.
For this reason, Microsoft released a tool called
SPDisposeCheck, which scans your code to tell you where you are not
releasing this memory because of not calling the Dispose() method. This tool saves you a lot of time and heartache in tracking down memory leaks.
Internet Explorer Developer Tools
Sometimes the best debugging tools are
the ones built right into the product. Internet Explorer provides you
the ability to browse your HTML, script, and Cascading Style Sheets
(CSS) code inside of its developer tools. To get to the developer
tools, press F12 in the browser. You can debug your HTML and CSS by
using the tree view and editing both sources on the fly. It also has a
built-in debugger for JavaScript so that you can set a breakpoint and
have the tools break when they hit your breakpoint. You get watch
windows, local variables, call stacks, and an immediate window called
the console. IE also includes a JavaScript profiler that shows you the
performance of your script code, including the number of times a
function was used and the amount of time it took. With these tools, you
can track down any issues in your client-side code.
Firefox and Firebug
If you use Firefox as your browser, you
can use Firebug as your HTML development and debugging tool. Firebug
provides similar functionality to the IE developer tools in the Firefox
environment.
Visual Round Trip Analyzer
The Visual Round Trip Analyzer (VRTA)
sits on top of the network monitor tool from Microsoft and is a free
add-on. It provides a graphic representation of how long it takes a
client to talk to a server. This information can then be used to
determine whether you are making excessive round trips, if your code is
slowing down the pages (for example, because of loading many small
JavaScript or CSS files), or if there are network issues causing any
problems between your application and the server.
Fiddler
No discussion of debugging tools would be complete without mentioning Fiddler (www.fiddlertool.com).
Fiddler is a web debugging proxy that logs all HTTP and HTTPS traffic
between your computer and the Internet. Fiddler enables you to inspect
all HTTP traffic, set breakpoints, and view your incoming and outgoing
data. It is an essential tool to help you understand what server
variables are coming back from your server, what their payload is, how
many calls your client-side code took, and other factors that provide
insight into your applications.
