Hi guys,

Last monday, we have released drop 7 of the SharePoint Guidance V2. You can get it here:

http://spg.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=26085

In this drop, we have tackled a couple of things:

• A couple of bugfixes and installation fixes.
• Created a Logging and Tracing implementation
• Added a Service locator
• Refactored code into a PartnerSiteDirectory class

For your viewing pleasure, we recorded a video to guide you through the drop:

Logging  and tracing

For any application, it’s important to write diagnostic messages to a log. Diagnostic information is invaluable when you want to identify and diagnose problems with your application.

While logging and tracing is in some respects similar, the audience and purpose are quite different:

Tracing

Tracing is a technique to help developers analyze and diagnose problems with their application. For a developer who has to hunt down a problem, you can never have too many tracing information. However, because the amount of trace information can be overwhelming (for a developer, but also for the system that has to write all the information), tracing levels should be adjustable at runtime.

What should you trace?

• Errors and exceptions
  If something goes wrong with your application, you want to know about it. Even if your code can handle the exception, it’s often beneficial to write a trace statement. For example, did a download fail, but you were able to retry. The user might not need to know, but you as a developer might be really interested in this information.
• Remote system calls
  In a service oriented world, it’s very common for an application to access functionality on a different machine. This is also a place where things go wrong often. Being able to trace the request and response messages can greatly help in debugging what goes wrong. Many frameworks, such as Windows Communication Foundation, allows you trace this information.
• Queries
  If your system is creating and executing queries, the text and the parameters of these queries can be a life saver when debugging an application. Note, queries are not limited to SQL queries against a database. Also consider CAML, Entity SQL and any other querying syntax that your app might use.
• Anything else you think is important
  There are a lot of other things that can be helpful for debugging. Use your imagination :)

Typically, tracing information goes to a log file on the machine that does the tracing.

Logging

Logging is a technique to help IT pro’s to detect, diagnose and troubleshoot problems with their applications. Often this information will be aggregated into a central monitoring system like Service Center Operation Manager (SCOM).

Information written to the log should be understandable and actionable by IT Pro’s. A message like “Object reference not set in method Foo()” can be helpful for a developer, but doesn’t really say anything to an IT Pro. However, a message like “Could not connect to database X, the connection timed out.” does make a lot of sense to an IT Pro.

What should you log?

• Known application failures
  Often there are situations where you can expect your applications to fail sometimes. For example, you’re calling web services. If there are network issues, the web service call will fail. This would be something the IT would be interested in.
• Installation or configuration issues
  If the installation or configuration of your app fails, the IT Pro wants to know about it. Usually they are the persons that do the installation and configuration.
• Unknown application failures
  If your application faces an unhandled exception, usually the IT Pro just wants to be informed that a certain area of the application is having issues. For example: “Authentication failed for unknown reason”.
• Situations that can potentially cause issues in the future.
  Sometimes you can proactively detect issues. For example, “the hard drive is becoming full. “ or “Deadlock detected in query x”. The application will often still work, but it can be an indication of deeper issues.
• Other actionable information.
  Again, this is not an exhaustive list. Be creative but keep your audience in mind :)

Typically, log information is stored in the EventLog, because this is easily consumed with tools like SCOM. However, some organizations might prefer storing this information in a central database.

Logging and tracing in Drop 7

In Drop 7, we have built a basic logging and tracing implementation.

The idea of this logging implementation is that you have a logging and tracing implementation that works out of the box. However, if you need more flexibility or have an existing logging implementation, you should be able to plug that in. For example, we’re thinking of supplying an Enterprise Library logging implementation for Sharepoint. If you don’t know or care about EntLib, you shouldn’t have to bite off the extra complexity that entlib brings. But if you need to, you should be able to plug it in easily.

The following code snippet shows how to use the logging API:

   1: ILogger logger = new SharepointLogger();

   2:  

   3: // Write a diagnostic statement (just to the ULS)

   4: logger.LogDiagnostic("Just executed query: " + camlQuery);

   5:  

   6: // Write a warning and a error message (both to the ULS and the EventLog)

   7: logger.LogWarning("Sharepoint list exeeds 2000 items. Listname = " + listName, SHAREPOINT_LIST_EXCEEDED);

   8: logger.LogError("Could not connect to database: " + databaseName, DATABASE_CONNECTION_EVENTID); 

   9:  

  10: // General purpose API

  11: logger.Log("logmessage", TraceSeverity.Verbose, myEventID, "MyCategory")

There are several methods like LogDiagnostic, LogWarning and LogError, that are explicit about the specific log scenario.

For our basic logging implementation we took the following approach:

• Warnings and errors should go to both the EventLog and the tracelog (ULS)
• Diagnostic messages should only go to the (ULS).

We decided to use the ULS for our tracing. This allows a developer to see his diagnostic messages in the context of sharepoint’s trace messages. If the developer is trying to diagnose a problem that is caused by an issue in sharepoint, he can more easily find the root cause.

Event sources for logging to the EventLog

When we are logging to the eventlog, you need to write to a specific Event Source. An Event Source specifies the name of an application that is allowed to write to the eventlog. Unfortunately, the asp.net user account by default doesn’t have the rights to create new event sources. So either you should allow the asp.net user to create the eventsources or you should pre create event sources on all your web servers.

For now, we took the approach of (ab)using the “Office Sharepoint Server” event source, because this should be available out of the box. In a future drop, we probably want to be able to configure the event source and probably the application log name.

Service locator

In your application code, you often need to have access to system level services. For example, you want to log messages or you want to do some type of data access and need a specific repository. Of course, you can new up the concrete implementation your service in your application code. However, if you want to be able to plug in different services, you’d need to change all the places where you’ve created the services.

A better way is to hide creation of services in a service locator. Instead of using:

SharepointLogger logger = new SharePointLogger()
logger.LogError("Wrong!");

Ilogger = new ServiceLocator.Current.GetInstance<ILogger>()
logger.LogError("Wrong!");

Now, your application code is no longer tied to any specific implementation of logger.

We have included a very simple ServiceLocator in this drop. It hard codes the coupling between the interfaces and their implementations. Still, this provides a lot of benefits, because the which concrete implementation is used is defined in a single location. The interface of this class was created using the interface from the Common Service Locator project.

In a future release, we might use a different technique. For example, we might build our own configuration based service locator or use Unity and the Common Service Locator for this.

Partner directory

While developing the Reference Implementation, we found a number of  places where we needed to know the ID of the currently logged on partner, or the URL to it’s collection. Since this information is stored in a central location, we decided to create a helper class to encapsulate this information.

Currently, the partner site directory has only public static methods, but now that we have a service locator, we can create this as a service behind a interface and use the service locator to find it. We’ll tackle that in a future iteration.

Conclusion

We hope you think the things we have been working on in this release are useful. Let us know what you think.

In the next release, we are looking at tackling (among other things) exception handling.

Keep practicing!

_Erwin