Editor's Note: The following is a guest post by SharePoint Server MVP Corey Roth as part of the MVP Award Program Blog's "MVPs for SharePoint" series. Corey Roth is a
solutions architect at Stonebridge specializing in SharePoint solutions in the
Oil & Gas Industry. Corey has recently been awarded the Microsoft MVP
award in SharePoint Server. He has always focused on rapid adoption of
new Microsoft technologies including SharePoint 2010, Visual Studio 2010, .NET
Framework 4.0, LINQ, and Silverlight. When it comes to SharePoint, he
specializes in ECM, Enterprise Search, and Business Connectivity
Services. As an active member of the SharePoint community, he often
speaks at user groups, Tech Fests, and SharePoint Saturdays. Corey is a member
of the .NET Mafia (www.dotnetmafia.com)
where he blogs about the latest technology and SharePoint. Corey is Vice
President of the Tulsa SharePoint Interest Group. He loves contributing
to the SharePoint community and currently has four active open source projects
on CodePlex.
There is a ton of excitement around SharePoint Online, part
of Microsoft’s Office 365 offering.
Developing applications in the cloud is really not much different than
developing a sandboxed solution. However, when it comes to debugging, we need
to think outside-of-the-box a little.
We’ve become a little spoiled by the great new SharePoint developer
tools that came with Visual Studio 2010.
We can still use those tools, but unfortunately in the cloud we don’t
have the luxury of F5 deployment. In
today’s article we will discuss some of your options for outputting debugging
information in the cloud. If you’re
looking for breakpoints, I’m sorry to disappoint you, but hopefully you can
leverage some of these techniques when coding your next SharePoint Online
application.
Start in the Sandbox
If you’re not familiar with developing in the cloud yet, you
might start by taking a look at my article, Office
365 How to: Build and Deploy a Web Part with SharePoint Online. This article walks you through step-by-step
how to create a sandboxed solution in Visual Studio 2010 using a local
SharePoint environment and then deploy it in the cloud. Another good resource is the SharePoint
Online for Office 365: Developer Guide.
Some of the debugging techniques demonstrated today are based on
recommendations in this guide. These
guides should get you quickly started creating applications for SharePoint
Online.
When it comes to debugging, the best place to start is in
your own local environment. Obviously
your local environment will never match the cloud exactly, but if you are
deploying dependent items such as content types and lists via feature, you’re
in a good place. This means you have a
reasonably good chance that your code referencing these items will work both in
the sandbox locally and in the cloud.
For today’s purposes, let’s start with a simple
web part that adds a task to the built-in Tasks list of a Team Site. Here’s what the code looks like.
using System;
using
System.ComponentModel;
using System.Web;
using System.Web.UI;
using
System.Web.UI.WebControls;
using
System.Web.UI.WebControls.WebParts;
using
Microsoft.SharePoint;
using
Microsoft.SharePoint.WebControls;
namespace SharePointOnlineDebugging.CloudDebuggingWebPart
{
[ToolboxItemAttribute(false)]
public class CloudDebuggingWebPart : WebPart
{
private Label TitleLabel;
private TextBox TitleTextBox;
private Button SubmitButton;
protected override void CreateChildControls()
{
// add controls to web part
TitleLabel = new Label() { Text = "Enter Task
Title: " };
TitleTextBox = new TextBox();
SubmitButton = new Button() { Text = "Add" };
// attach event handle to click event
SubmitButton.Click += new EventHandler(SubmitButton_Click);
Controls.Add(TitleLabel);
Controls.Add(TitleTextBox);
Controls.Add(SubmitButton);
}
void SubmitButton_Click(object sender, EventArgs e)
{
using (SPSite siteCollection = new SPSite(SPContext.Current.Site.ID))
{
using (SPWeb site =
siteCollection.OpenWeb(SPContext.Current.Web.ID))
{
SPList tasksList =
site.Lists["Tasks"];
SPListItem newItem =
tasksList.Items.Add();
newItem["Title"] =
TitleTextBox.Text;
newItem.Update();
}
}
}
}
}
The code simply creates a label, textbox, and
button. When the button is clicked, it
gets a reference to the Tasks list of
the current site and then adds a new item.
I can first verify that this code works correctly by testing it locally
on my own SharePoint server. I can debug
it and resolve any issues there before deploying the solution package to
SharePoint Online. Once you’re happy
with your solution locally, it’s time to send it to the cloud. Here is what our web part looks like when
deployed to SharePoint Online.
![]()
Before we start debugging, let’s take a look and see how
SharePoint Online handles exceptions. As
an example, let’s produce an exception by specifying the wrong name for the Tasks list. We’ll use this exception throughout the rest
of the article.
SPList tasksList =
site.Lists["Tasks List"];
When we try to insert a task, the reference to
the wrong list in the above code generates an exception and this is what the
user sees.
![]()
This is not exactly a useful error message for the user or
the developer. At this point, we have
absolutely no way to figure out what went wrong. We can’t even go look in the ULS logs since
we’re in the cloud. So what do we
do? We have to go back to more traditional
debugging techniques that some of us used years ago. We
have to add code to do our debugging.
This might sound archaic or even insane to some of you, but it’s really
our best way to troubleshoot in the cloud.
Developers have been using techniques like this for years long before we
even dreamed of breakpoints. It really
does work pretty well.
To do our debugging, we’ll create a method to
handle the debugging and insert a call to it in our code where we need it. I know it’s not as glamorous as pressing the
F5 button and a lot of it you may consider common sense. However, I hope it helps spark some ideas in
others to create unique debugging solutions.
Literal Debugging
We want to track down the cause of this exception, so I am
going to add a try / catch block around our code. When an exception is caught, we’ll use a new debugging
method that we created to display the text of the exception.
try
{
using (SPSite siteCollection = new SPSite(SPContext.Current.Site.ID))
{
using (SPWeb site = siteCollection.OpenWeb(SPContext.Current.Web.ID))
{
SPList tasksList = site.Lists["Tasks List"];
SPListItem newItem = tasksList.Items.Add();
newItem["Title"] =
TitleTextBox.Text;
newItem.Update();
}
}
}
catch (Exception exception)
{
DebugUsingLiteral(exception.ToString());
}
Our DebugUsingLiteral
method simply adds a literal to the page and dumps the text of the exception to
the page so that you can see it.
private void DebugUsingLiteral(string message)
{
Controls.Add(new Literal() { Text = message });
}
Here is what the exception looks like now that it is caught.
![]()
Not the prettiest solution, but at least we know what the
issue is now. It cannot find the list as
we had expected.
Comment Debugging
That solution above works but it’s not very user
friendly. Let’s pretty it up a bit by
writing the exception to an HTML comment.
This will allow us to view the source of the HTML to see the exception
and the user won’t have to see it. Let’s
replace our calls to DebugUsingLiteral
with a new method DebugUsingLiteralComments. Here is what the new method looks like.
private void
DebugUsingLiteralComments(string message)
{
Controls.Add(new Literal() { Text = string.Format("<!-- {0} -->", message) });
}
When we try it out, we now no longer see the error message.
![]()
Looking at the HTML source of our page, we can find our
exception.
![]()
Of course the user has no clue it failed either. However, we can fix that pretty easily by
adding a new control to our debugging method to display a user friendly error
message.
private void DebugUsingLiteralCommentsUserFriendly(string message, string userFriendlyMessage)
{
Controls.Add(new Literal() { Text = string.Format("<!-- {0} -->", message) });
Controls.Add(new Label() { Text = userFriendlyMessage });
}
When the user gets the exception now, they see a
more user friendly error message.
![]()
Handling verbose debugging
At times, we may also want to write verbose non-exception
information to the screen as well. Now would be a good time to get reacquainted
with the C# compiler directive, #if DEBUG.
Our strategy here is that if the solution was built using the Visual
Studio debug configuration, we’ll output additional debugging information. When in release mode, nothing will be logged. We’ll use the same DebugUsingLiteralComments method that we used above. Take a look at the snippet below.
#if DEBUG
DebugUsingLiteralComments("Getting
reference to Tasks List.");
#endif
SPList tasksList =
site.Lists["Tasks List"];
#if DEBUG
DebugUsingLiteralComments("Creating new
item.");
#endif
The #if DEBUG tells the compiler to only execute the lines
to output debugging information if the current Visual Studio build
configuration is set to Debug. When we execute the code, our HTML now has
our debugging lines in it.
![]()
Why did we not just put the compiler directives inside the DebugUsingLiteralComments method? This is just a slight code optimization. The release version of the code never has to
call the method itself when the debugging configuration is not used. It may be a minimal performance improvement,
but since you have limited resources in the cloud, it’s probably worth
considering. I could be totally wrong of
course.
When we are ready to ship the code, we simply
recompile in release mode and the debugging lines are gone.
![]()
When
you do compile in release mode, don’t forget to get your .wsp file from the release folder instead of the debug folder. Another thing to note when uploading all of
these solutions packages to the cloud is that you need to deactivate the
existing solution first prior to uploading a new version of it. However, you do not need to delete the
existing solution package prior to uploading the new version.
Debugging a using List
The SharePoint Online Developer Guide recommends using a
list for debugging. This is a great
technique because it allows you to view all of your debugging information in
one place. Plus, you can take advantage
of all the features list have such as sorting and alerts. For today’s example, I am going to keep
things simple. I want to create a new
list with a few relevant columns to collect my information. In a fully functional solution, we would probably
create site columns, a content type and a dedicated class library to host the
code to write to the list.
Let’s start by defining the information I want
to keep track of in my debugging list. This is on top of the columns we already
have such as Modified Date.
![]()
To
save time, I will create this list using the SharePoint UI. I’ll provide the complete solution including
features to deploy the list using CAML in the future. We’ll create a custom list named Logs.
![]()
After we create the list, I create the columns listed in the
table above (note: Title is already present).
![]()
Now we just need a bit of code to write to the log. We’ll put the logging code in a separate
class that we’ll call CloudLog. In that class, we’ll create a static method
that takes parameters matching the site columns on our Logs list, title, severity, and description. We don’t need to pass the URL field since
we can infer that from the HttpContext.
For severity, I created an
enum for convenience.
public enum CloudLogSeverity
{
Information,
Warning,
Error
}
The code of the method itself should look pretty
familiar. We’re just inserting an item
into a list like before. Here is what
the class looks like.
using System;
using
System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Web;
using
Microsoft.SharePoint;
namespace
SharePointOnlineDebugging
{
public class CloudLog
{
public static void DebugUsingList(string title, CloudLogSeverity severity, string description)
{
try
{
using (SPSite siteCollection = new SPSite(SPContext.Current.Site.ID))
{
using (SPWeb site =
siteCollection.OpenWeb(SPContext.Current.Web.ID))
{
SPList logsList =
site.Lists["Logs"];
SPListItem newItem = logsList.Items.Add();
newItem["Title"] = title;
newItem["Severity"] = severity.ToString();
newItem["Description"] = description;
SPFieldUrlValue pageUrlFieldValue = new SPFieldUrlValue();
pageUrlFieldValue.Url = HttpContext.Current.Request.Url.ToString();
newItem["Url"] = pageUrlFieldValue;
newItem.Update();
}
}
}
catch (Exception exception)
{
}
}
}
}
We get a reference to the Logs list and then we just insert a new item. Once we set the values on the list item we
call SPListItem.Update() to write the
entry to the list. This code inserts
items into lists which of course has the potential to cause exceptions. I didn’t want exceptions in our logging code
to affect the rest of the application so currently I have an empty catch block
in the implementation. I know that’s not
really a good practice, but I really couldn’t think of a good option to catch
additional errors like this.
To call the method, I update the code in our catch block as
follows.
catch (Exception exception)
{
CloudLog.DebugUsingList("Error
creating new item.", CloudLogSeverity.Error, exception.ToString());
}
When the exception occurs, an item is logged to
the list. We can then view the list to
see the details of the exception.
![]()
In a complete implementation, I could see additional
overloads of the DebugUsingList
method to serve a variety of needs. We
could allow the developer to pass in more or less parameters depending on his
or her needs. There could be methods
that specifically log errors or information.
Perhaps, we could have methods that write additional data to the list. There are many possibilities on what we can
do to fully customize our debugging experience.
One thing to note about this approach is that the user
running the application must have write permissions on the Logs list. If the user
doesn’t, no information can be logged. To
do this, I stopped permission inheritance on the list and I added contribute
permission (technically more than needed) to the Viewers and Visitors
groups.
![]()
To
test my solution, I logged in as a non-administrator, Test User, and generated the error.
I then confirmed that the item written to the list was created by my Test
User account.
![]()
Another
issue to consider with this approach is that you will likely need to perform
some maintenance on this list. On a
large site with lots of logging, this list could grow quite quickly. You will need to create filters on the list
or purge it periodically to prevent list throttling. You also need to be mindful that logging to
the list will use some resources against your quota. Your quota should be monitored if you intend
to leave logging on for long periods of time.
Debugging with the Developer Dashboard?
When I was coming up with new debugging techniques, the
developer dashboard was originally going to be my recommended solution. Using the SPMonitoredScope
class allows you to monitor the performance of your code and it allows you to
write directly to the developer dashboard.
Unfortunately, this class is not available in sandboxed solutions so we
can’t use it with SharePoint Online. You
still have plenty of other debugging techniques available to you that were
presented in this article though.
Community Involvement
I think there is a great opportunity for the community to
work together and build a great logging framework for SharePoint Online. The solution I have shown you today is just
the beginning of what could be a grand community driven solution on CodePlex. The solution would consist of features to
deploy, site columns, content types, the list, as well as classes you can
leverage to do your logging. If you are
interested in helping out, feel free to contact me. I think we can build a great solution.
![]()
