Sharepoint 2010: Teil 7 – Entwickeln mit Sharepoint


Es ist an der Zeit in unsere Artikelserie endlich “richtig” mit Sharepoint 2010 zu arbeiten, für einen Softwareentwickler kann das nur eins bedeuten –> Code – in Form der Sharepoint API.

Anhand der Umsetzung eines kleinen (Echt-Welt) Beispiels, sehen wir uns die Visual Studio 2010 Umgebung für Sharepoint an, die Feature/Solution Infrastruktur von Sharepoint sowie die API selbst.

Die Anforderung sieht folgendermassen aus: Eine Sharepoint Liste wird via Import aus einem externen System mit E-Mail Adressen befüllt. Wird nun ein Element in der Liste verändert soll an die entsprechende E-Mail Adresse eine Nachricht versandt werden.

Findige Leser werden einwerfen- “Dass geht Out-of-the-Box” – stimmt! ABER: Diese Anforderung stammt aus einem echten Projekt und wie immer liegt der Teufel im Detail. Nur so viel sei gesagt, in diesem konkreten Fall gehts nicht mit Bordmittel – daher ergibt sich daraus ein nettes kleines Programmierbeispiel für Blogs etc. 🙂

Umgesetzt wird die Anforderung mit der Sharepoint Objektmodell mit einem “Event Receiver”. Sharepoint bietet eine grosse Anzahl an “Event Receiver” an. Kurz gesagt ermöglichen sie, das “Reagieren” auf bestimmte Ereignisse in der Sharepoint Infrastruktur. Umgesetzt wird ein EventReceiver ganz einfach als Assembly, welche in den GAC wandert.

Los gehts – Wir legen in Visual Studio 2010 ein neues Projekt vom Typ “Sharepoint 2010 – Event Receiver” an.

A1

Diese Vorlage und der folgende Wizard erledigen viele Konfigurationsaufgaben für uns, die mit Sharepoint 2007 noch alle händisch zu tätigen waren, wir müssen uns nur mehr auf unsere Business Logik konzentrieren.

Im Wizard, der erscheint sobald man auf “Weiter” klickt, lassen wir eine “Sandboxed-Solution” erstellen, das heisst wir können ausserhalb unserer SiteCollection nichts “anstellen” mit unserem eigenen Code. Wichig ist die nächste Seite, hier wird eingestellt auf welche Listenvorlagen der EventReceiver reagieren soll und auf welches Ereignis.

Es gibt grundsätzlich 5 Gruppen von Ereignissen: Listenereignisse, Listenelementereignisse, Webereignisse, Workflow- und Emailereignisse.

Fürs Beispiel wählen wir Listelementereignisse (List Item Events) und das Ereignis “An item was updated” –> Wir reagieren also NACHDEM ein Element geändert wurde. Das Ereignis “An item is being updated” wäre das Pendant dazu, BEVOR ein Update passiert.

Als Ereignisquelle wählen wir im Beispiel “Custom List”, also Benutzerdefinierte Liste. Hier würde in einem realen Projekt noch granularer eingeschränkt auf “Task” etc.

Ein Klick auf “Finish” erzeugt alle notwendigen Konfigurationsdateien, damit unsere Solution sofort auf Knopfdruck “Deployed” werden kann – dazu am Ende des Artikels mehr.

Ist die Erzeugung der Solution fertig, wird im Code Editor sofort die Klasse EventReceiver1 angezeigt. Diese Klasse leitet von SPItemEventReceiver ab und stellt alle benötigten EventHandler bereit um auf die Sharepoint Ereignisse zu reagieren. Weiters ist der EventHandler ItemUpdated sofort erzeugt worden. Wir brauchen nur mehr “ausfüllen” mit unserer Businesslogik.

   1: public class EventReceiver1 : SPItemEventReceiver
   2: {
   3:     public override void ItemUpdated(SPItemEventProperties properties)
   4:     {
   5:         base.ItemUpdated(properties);
   6:     }
   7: }

Drei Dinge müssen passieren, damit unsere Spezifikation umgesetzt wird.

- Auslesen der E-Mail Einstellungen

- Auslesen der E-Mail Adresse aus dem Listenelement

- Versenden der Email

 

  • Auslesen der E-Mail Einstellungen

Die E-Mail Einstellungen sollen “von aussen” konfigurierbar an den EventReceiver übergeben werden. Dinge wie Absenderadresse, Subject und Text sollten nicht hardcoded werden.

Dies kann einfach erreicht werden indem man die Eigenschaft “ReceiverData” von SPListeItemEventProperties verwendet. Mithilfe dieser Eigenschaft lassen sich beliebige Daten übergeben. Im Beispiel werden die Daten einfach in folgenden Format mit übergeben

FROM:sharepoint@codeforce.at|Subject:TestMail|Body:This is a test!

   1: public static EmailSettings GetEmailSettings(string eventData)
   2: {
   3:     var sections = eventData.Split(new[] { "|" }, StringSplitOptions.RemoveEmptyEntries);
   4:     var settings = new EmailSettings
   5:     {
   6:         FromAdress = sections[0].Split(':')[1],
   7:         Body = sections[1].Split(':')[1],
   8:         Subject = sections[2].Split(':')[1],
   9:         EmailFieldName = sections[3].Split(':')[1]
  10:     };
  11:     return settings;
  12: }

Und der Aufruf dazu:

   1: var settings = GetEmailSettings(properties.ReceiverData);

Im Beispiel wurde jegliche Fehlerbehandlung entfernt, die sollte natürlich nicht fehlen! Wie wir die Eigenschaft “ReceiverData” befüllen, sehen wir am Ende des Beispiels.

  • Zugriff auf das Listenelement – Auslesen der Email Adresse

Interessant wirds im 2. Punkt, hier müssen wir via Objektmodell auf Inhalte der Liste zugreifen. Auch keine Hexerei!

   1: var address = properties.ListItem.GetFormattedValue(emailFieldName);

Über das Argument “properties” der Methode “ItemUpdated” kommen wir einfach an des Listenelemnt, welches das Ereignis ausgelöst hat. Um nun ein gewisses Feld abzurufen bietet sich die Methode “GetFormattedValue()” an, da sie die Daten eines Feldes IMMER als formatierten string zurückliefert. Je nach Feldtyp kann das auch zu, nur mehr bedingt lesebaren Ausgaben führen – falls das Feld einen komplexen Typ wie “Lookup” oder “BusinessData” hat. Alternativ kann auch einfach der Indexer verwendet werden.

   1: var address = properties.ListItem[emailFieldName];
  • Versand der E-Mail

Am einfachsten gelingt dies mit einer Hilfsmethode aus der statischen Klasse SPUtility – die EMail wird dann nämllich sofort versandt und “umgeht” die Sharepoint “Immediate Alert” Architektur. Das hat den Vorteil, dass man beim Testen nicht immer warten muss, bis der Timer Dienst “Immediate Alerts” versendet.

   1: public bool SendMail(EmailSettings settings,string toAdress, SPWeb web)
   2: {
   3:     return SPUtility.SendEmail(web, false, false, toAdress, settings.Subject, settings.Body);
   4: }

Soweit ist unser Code damit fertig. Im Anhang findet sich die komplette Klasse.

Wie wird nun unser EventReceiver in Sharepoint registriert?

Im Visual Studio Projekt finden sich unter dem Punkt “Features” einige Dateien welche aus der Vorlage erzeugt wurden. Ein Feature in Sharepoint Terminologie ist die “Verpackungseinheit” für alle Dinge, die man ausrollen will in die Farm. Ein Feature besteht aus zwei oder mehr XML Dateien, die die Inhalte beschreiben. Visual Studio 2010 bietet für Features einen eigenen Designer, also ist es nicht mehr nötig das genaue XML Schema zu kennen.

Öffnet man mit Doppelklick ein Feature sieht man dessen Inhalt – der EventReceiver in unserm Fall. Die ganze “Magie” – also die Zuordnung unseres Codes zu dem Sharepoint Event passiert in der Datei Elements.xml, die man mittels Kick direkt im Feature Designer öffnet (Ein Klick auf das kleine
“ + Files “ lässt den Link zur Elements.xml erscheinen).

   1: <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
   2:
   3:   <Receivers ListTemplateId="107">
   4:     <Receiver>
   5:       <Name>List Mailer</Name>
   6:       <Type>ItemUpdated</Type>
   7:       <SequenceNumber>100</SequenceNumber>
   8:       <Assembly>TaskListFeatures, Version=1.0.0.0, Culture=neutral, PublicKeyToken=7eaab9b475a29bf8</Assembly>
   9:       <Class>TaskListFeatures.Features.TaskMailer.TaskListMailerEventReceiver</Class>
  10:       <Data>From:sharepoint@codeforce.at|Body:Hello World!|Subject:Test Mail|FieldName:email Adress</Data>
  11:       <Filter>
  12:       </Filter>
  13:     </Receiver>
  14:   </Receivers>
  15: </Elements>

Hier im Element Manifest, sieht man die Zuordnung zur Liste. Das Element “Receivers” spezifiziert ein oder mehrere Receiver Klassen auf bestimmten Listenvorlagen. Es wird auf eine Assembly und eine Klasse verwiesen, die das Event verarbeitet. Wichtig ist hier auch die Sequence! Es kann sein, dass mehrere Receiver aufs selbe Event reagieren, mit der Sequence kann man sie in eine Reihenfolge bringen.

Hier wird auch mit dem Element “Data” die Konfiguration gespeichert. Die Zeichenfolge in “Data” steht dann in der Eigenschaft ReceiverData, welche wir für die Email Einstellungen verwendet haben zu Verfügung.

Soweit haben wir unseren Receiver fertig, mit Rechts-Klick im Solution Explorer kann das Ganze “Deployed” werden. Visual Studio 2010 verpackt dabei alle Features in eine Sharepoint Solution (ein CAB Archiv mit der Endung .wsp") und rollt diese am Server aus.

Geschafft! Sobald nun in einer Liste vom Typ “Custom List” ein Element geändert wird, feuert unser EventReceiver!

Mehr zur Feature/Solution Infrastruktur sehen wir uns im nächsten Artikel wieder Hands-on an.


Skip to main content