Wie viele von euch wissen, eignen Sich SharePoint EventReceivers wunderbar, um sich an SharePoint-Events zu hängen und darauf zu reagieren, um eigenen Code auszuführen. Oft werden Events z. B. zur Validierung von eingegebenen Werten eingesetzt.
Nachfolend eine Liste der verfügbaren Events für SharePoint 2007:
Events für Websites (SPWeb) - SPWebEventReceiver:
|
Before: |
After: |
|
SiteDeleting
WebDeleting
WebMoving |
SiteDeleted
WebDeleted
WebMoved |
Events für Listen (SPList) - SPListEventReceiver:
|
Before: |
After: |
|
FieldAdding
FieldUpdating
FieldDeleting |
FieldAdded
FieldUpdated
FieldDeleted |
Events für Listenelemente (SPList) - SPItemEventReceiver:
|
Before: |
After: |
|
ItemAdding
ItemUpdating
ItemDeleting
ItemAttachmentAdding
ItemAttachmentDeleting
ItemCheckingIn
ItemCheckingOut
ItemFileMoving
ItemUncheckingOut |
ItemAdded
ItemUpdated
ItemDeleted
ItemAttachmentAdded
ItemAttachmentDeleted
ItemCheckedIn
ItemCheckedOut
ItemFileConverted
ItemFileMoved
ItemUncheckedOut |
Events für E-Mail-Empfang (SPEmailEventReceiver):
|
Before: |
After: |
|
|
EmailReceived |
Wieso Before und After?
Wenn Ereignisse vor der tatsächlichen Ausführung (z. B. löschen, auschecken, ändern, ...) ausgelöst werden sollen, benutzt man synchrone Events. Wenn Ereignisse nach der tatsächlichen Ausführung ausgelöst werden sollen, kommen asynchrone Events zum Einsatz.
Konkret:
Before-Events werden synchron, After-Events asynchron abgearbeitet. Z. B. wird ItemAdding vor dem tatsächlichem Hinzufügen eines Elementes ausgeführt, ItemAdded erfolgt nach dem Hinzufügen des Elementes.
Nachfolgend nun ein EventReceiver-Beispiel, indem übeprüft wird, ob während der Erstellung einer Aufgabe der Titel einen entsprechenden Wert enthält (in meinem Beispiel "Test"). Ebenfalls möchte ich verhindern, dass der Titel nachträglich geändert wird.
Um dies zu erreichen, habe ich eine neue Klasse erstellt, die sich von der Klasse SPItemEventReceiver ableitet.
Die eigentliche Überprüfung vor dem Speichern erfolgt wie zuvor beschrieben in der Methode ItemAdding:
public override void ItemAdding(SPItemEventProperties properties)
{
if (properties.AfterProperties["Title"].Equals("Test"))
{
properties.Cancel = true;
properties.ErrorMessage = "This value is invalid!";
}
}
Falls der Inhalt in der Spalte "Title" dem Wert "Test" entspricht, wird die angegebene Fehlermeldung ausgegeben. Das neue Listenelement wird in diesem Fall nicht erstellt.
Die Überprüfung vor dem Speichern eines geänderten Listenelementes erfolgt in der Methode ItemUpdading:
public override void ItemUpdating(SPItemEventProperties properties)
{
if (properties.AfterProperties["Title"] != properties.ListItem["Title"])
{
properties.Cancel = true;
properties.ErrorMessage = "Title cannot be changed!";
}
}
Hier wird der Originalwert mit dem geänderten Wert aus der Spalte "Title" verglichen. Falls die beiden Werte unterschiedlich sind, wird die angegebene Fehlermeldung ausgegeben.
Zugriff BeforeProperties / AfterProperties / ListItem (Vergleich Vorher/Nachher):
Um leichter erkennen zu können, wann über welche Eigenschaften welche Werte zurückgegeben werden, habe ich die folgende Übersicht erstellt:
Für Listen gilt:
|
Listenelement |
BeforeProperties |
AfterProperties |
properties.ListItem |
|
ItemAdding |
Kein Inhalt |
Neuer Wert |
NULL |
|
ItemAdded |
|
Neuer Wert |
Neuer Wert |
|
ItemUpdating |
|
Geänderter Wert |
Original Wert |
|
ItemUpdated |
|
Geänderter Wert |
Geänderter Wert |
|
ItemDeleting |
|
|
Original Wert |
|
ItemDeleted |
|
|
NULL |
Für Dokumentbibliotheken gilt:
|
Bibliothekelement |
BeforeProperties |
AfterProperties |
properties.ListItem |
|
ItemAdding |
Kein Inhalt |
|
NULL |
|
ItemAdded |
|
|
Neuer Wert |
|
ItemUpdating |
|
Geänderter Wert |
Original Wert |
|
ItemUpdated |
|
Geänderter Wert |
Geänderter Wert |
|
ItemDeleting |
|
|
Original Wert |
|
ItemDeleted |
|
|
NULL |
Download Codebeispiel:
Das Beispielprojekt habe ich euch bereitgestellt und kann in einer englischen Teamsite über die Websitefeatures aktiviert/deaktiviert werden. Der EventReceiver hängt sich an die Liste Aufgabenliste "Tasks".
Ausblick SharePoint 2010:
Mit SharePoint 2010 werden zusätzliche Events bereitgestellt. In einem
früheren Blogpost von uns findest du weitere Informationen dazu!