Im Ankündigungspost für die SharePoint 2010 Guidance Library habe ich die verschiedenen fertigen Komponenent, welche die Bibliothek dem SharePoint Entwickler bietet schon angesprochen. Nun ist es an der Zeit, die Dinge genauer zu betrachten.
Als erstes ist der neue SharePoint Logger an der Reihe. Mit der Logging Komponente kann sehr einfach in die ULS Logs (im 14 ‘Hive’), wie auch in die Windows Event Logs von SharePoint geschrieben werden. Eine RIESEN Erleichterung, da bisher zum schreiben von Trace Informationen, sehr viel, sehr aufwendiger Code notwendig war.
Warum wollen wir überhaupt ins ULS Log schreiben? Ein klassisches Entwicklungsszenario: Man entwickelt, eine tolle Solution auf der eigenen Virtuellen Maschine, auf der alles perfekt konfiguriert ist, dann wird das Paket zum Kunden ausgerollt und plötzlich geht nichts mehr. Debuggen ist nicht möglich auf den Servern des Kunden. Das klassische – Works on my machine Szenario! Und welcher SharePoint Developer kennt das nicht – der möge ein Kommentar hinterlassen 
Ein kleines Beispiel soll zeigen, wie einfach Logging nun ist. Gestartet wird mit dem Download der SharePoint Guidance Library. Nach dem Entpacken befindet sich im Verzeichnis Source, der komplette Quellcode, welcher in die eigenen Lösungen integriert werden kann. Dieser muss nur kompiliert werden. Zwei Assemblies sind notwendig, damit man die Funktionen der Library nutzen kann:
- Microsoft.Practices.SharePoint.Common.dll
- Microsoft.Practices.ServiceLocation.dll
Nachdem die Assemblies erzeugt sind, erstellen wir unser neues Beispielprojekt – eine leere SharePoint Solution, dieser Solution fügen wir Referenzen auf die beiden obigen Assemblies hinzu. Als nächstes wird ein Element vom Typ “EventReceiver” eingefügt. Dieser Receiver wird unsere Testklasse zum Loggen enthalten.
Abbildung 1: Einfügen eines neuen EventReceivers
Los gehts mit dem Code:
Folgende using Direktiven werden benötigt
1: using Microsoft.Practices.SharePoint.Common;
2: using Microsoft.Practices.ServiceLocation;
Im EventReceiver wird das Ereignis “ItemAdded” behandelt, welches feuert, nachdem in der zugewiesenen Liste ein Eintrag erfolgt ist.
Zunächst erzeugen wir uns einen neuen Logger. Dies geschieht nicht direkt mittels dem “new” Keyword, sondern gleich mit dem ServiceLocator, welcher ebenfalls Teil der Library ist. Der ServiceLocator wird im nächsten Artikel genauer beleuchtet.
1: //Aktueller Locator der SiteCollection
2: var serviceLocator = SharePointServiceLocator.GetCurrent();
3: //Implementierung von ILogger holen
4: logger = serviceLocator.GetInstance<ILogger>();
Der SharePointLogger bietet zwei Methoden an, welche Logging bzw. Tracing ermöglichen. LogToOperations(..) und LogToDeveloper(..). Operations bezeichnet hier das Schreiben ins Windows Event Log und Developer das Tracing ins SharePoint ULS Log.
Unser kleines Beispiel sieht wie folgt aus.
1: public override void ItemAdded(SPItemEventProperties properties)
2: {
3: ILogger logger = null;
4: var area = "Custom EventReceivers";
5: var category = "Execution";
6: var areaCategory = string.Format("{0}/{1}", area, category);
7:
8: try
9: {
10: base.ItemAdded(properties);
11: //Aktueller Locator der SiteCollection
12: var serviceLocator = SharePointServiceLocator.GetCurrent();
13: //Implementierung von ILogger holen
14: logger = serviceLocator.GetInstance<ILogger>();
15: //Test: Auslösen einer Exception
16: if (properties.ListItem.Title == "Error")
17: throw new Exception("The list item title told me to raise an exception");
18:
19: SPSecurity.RunWithElevatedPrivileges(() => logger.LogToOperations(
20: string.Format(
21: "SpgTest.EventReceiver worked fine on {0}",
22: properties.ListTitle),
23: (int) EventId.Success,
24: EventSeverity.Verbose,
25: areaCategory));
26:
27: }
28: catch (Exception ex)
29: {
30: //Exception in Trace schreiben (ULS Log)
31: if (logger != null)
32: logger.TraceToDeveloper(ex, "Error from SpgTest.EventReceiver",
33: (int)EventId.Error,
34: SandboxTraceSeverity.Unexpected,
35: areaCategory);
36: }
37: }
Bei Erfolg, schreiben wir eine Nachricht ins Event Log, mit Severity Level “Verbose”. Wichtig ist immer eine Category und eine Area anzugeben, damit es den Administratoren, welche die Logs durchsuchen müssen leichter fällt, Nachrichten einzuschränken. Die Area und Category werden im Format Area/Category zusammengehängt. Schreibt man ins Windows Event Log entspricht die Area dem “Event Source Name” und die Category entspricht “Task Category”.
Dasselbe gilt auch beim Tracing in die ULS Logs. Area und Category erleichtern das Suchen in den Textfiles ungemein. Ein weiterer wichtiger Punkt ist eine eindeutige EventId. Sie ermöglicht es zusammengehörige Ereignisse zu identifizieren. Hier bietet es sich immer an eine Enumartion zu erstellen, welche die verschiedenen IDs darstellt.
1: public enum EventId : int
2: {
3: Success,
4: Error,
5: Unknown
6: }
Soweit ein kurzer Einblick in die spannenden Möglichkeiten der SharePoint Guidance Library. Im nächsten Artikel steht der neue Service Locator im Mittelpunkt – ein Muss für echte Softwareentwickler.
Downloads:
SharePoint 2010 Guidance Library
Andreas Aschauer
Mail: andreas.aschauer@codeforce.at
Twitter: www.twitter.com/CodeForceAT
Subscribe