Vorgehensweise: Erstellen von Sandkasten-Workflowaktionen

Artikel
09/18/2014

Letzte Änderung: Freitag, 16. Juli 2010

Gilt für: SharePoint Server 2010

Inhalt dieses Artikels
Szenario für Sandkasten-Workflowaktionen
Übliche Verwendungsszenarien für Sandkasten-Workflowaktionen
Tipps für die Verwendung von Sandkasten-Workflowaktionen

In diesem Thema wird die Erstellung von Sandkasten-Workflowaktionen erläutert, die unter Verwendung des SharePoint-Listenobjektmodells in externen Listen lesen.

Diese Anleitung entspricht dem Sandkastenworkflow-Beispiel, das ein Bestandteil von Microsoft SharePoint 2010 Software Development Kit (SDK) ist. Weitere Informationen dazu, wie Sie dieses Beispiel erhalten, finden Sie unter Codebeispiel: Beispiel für Sandkastenworkflow.

Sandkasten-Workflowaktionen sind Codefunktionen, die in einem deklarativen Workflow-Designer verwendet werden können, und die von einem deklarativen Workflow aufgerufen werden. Eine Sandkasten-Workflowaktion wird in Microsoft Visual Studio geschrieben und zum SharePoint-Lösungskatalog hochgeladen. Diese Aktionen werden isoliert ausgeführt, um sicherzustellen, dass der Hauptsystemprozess geschützt ist und Grenzen respektiert werden.

Durch die Verwendung von Sandkasten-Workflowaktionen können Sie ein Element in einer externen Liste einmal lesen und auf eine Weise speichern, dass diese Daten erneut verwendet werden können. Auf diese Weise wird die Anzahl der mit einer externen Liste ausgeführten Lesevorgänge reduziert, die beim Arbeiten mit SharePoint-Workflowaktivitäten ausgeführt werden müssten. Beim Lesen einer Spalte in einer externen Liste unter Verwendung der integrierten SharePoint-Workflowaktivitäten wird eine Read List-Methode (Finder) und eine Read Item-Methode (SpecificFinder) aufgerufen. Dies ist unnötig. Sandkasten-Workflowaktionen verhindern die unnötigen Aufrufe und verringern die Belastung des externen Systems.

Szenario für Sandkasten-Workflowaktionen

Normalerweise verwenden Sie einen Workflow mit Microsoft Business Connectivity Services (BCS) in einem Szenario, in dem bedingte Genehmigungen erforderlich sind, und die Bedingung der Genehmigung auf einem Wert basiert, der in einem externen System gespeichert ist. Stellen Sie sich beispielsweise ein Kostengenehmigungsszenario vor, in dem der Kostenbericht nur zur Genehmigung an einen Vorgesetzten gesendet wird, wenn die Gesamtkosten einen bestimmten Grenzwert überschreiten. Wenn die Kosten unterhalb des Grenzwerts liegen oder gleich diesem sind, werden die Kosten automatisch genehmigt und benötigen keine explizite Genehmigung. Da der Kostengrenzwert variieren kann, wird er in einem externen System gespeichert und später vom Workflow in einer externen Liste nachgeschlagen.

Das Beispiel in diesem Thema führt Sie durch die einzelnen Schritte für die Erstellung einer externen Liste, die auf dem externen Inhaltstyp Grenzwert basiert, einem Workflow und der Variable zum Nachschlagen.

Hinweis
In diesem Szenario wird davon ausgegangen, dass Sie vertraut mit der Verwendung von SharePoint Designer-Listenelementaktivitäten für externe Listen sind, wenn Sie diese mit SharePoint-Listen verwendet haben. Der Hauptunterschied der Funktionsweise von Listenelementaktivitäten ist der, dass Elemente nicht mithilfe einer ID gefunden werden, sondern mithilfe ihrer identifizierenden Spalte.

So erstellen Sie den Grenzwertworkflow unter Verwendung von SharePoint Designer-Aktivitäten

Erstellen Sie in SharePoint Designer einen externen Inhaltstyp mit dem Namen Grenzwert.

Der externe Inhaltstyp sollte zwei Felder besitzen: MitarbeiterID und Grenzwert (für den Grenzwert).
Erstellen Sie eine externe Liste unter Verwendung des externen Inhaltstyps Grenzwert, und nennen Sie diese Grenzwerte.
Erstellen Sie eine Dokumentbibliothek für Kostenberichte, und nennen Sie diese Kostenberichte. Fügen Sie anschließend eine Spalte für MitarbeiterID hinzu.
Klicken Sie in SharePoint Designer in der Dokumentbibliothek Kostenberichte auf Neu und dann auf Listenworkflow.
Geben Sie einen Namen für den Workflow und eine Beschreibung ein, und klicken Sie dann auf Weiter.

Jetzt können Sie im Workflow-Designer neue Aktivitäten hinzufügen.
Fügen Sie die Aktion Workflowvariable festlegen ein.
1. Klicken Sie auf den Hyperlink der Workflowvariablen, und klicken Sie auf Neue Variable erstellen.
  
  Nennen Sie diese neue Variable Grenzwert.
2. Klicken Sie auf den Wert und anschließend auf die Schaltfläche fx, um das Nachschlagen in der externen Liste zu erstellen.
3. Unter Datenquelle klicken Sie auf die externe Liste Grenzwerte.
  
  Dies ist die Datenquelle, aus der die Grenzwerte abgerufen werden.
4. Wählen Sie unter Quellenfeld das Feld aus, das den Grenzwert anzeigt. In diesem Beispiel ist dies Grenzwert.
Legen Sie fest, was Sie zum Nachschlagen des Elements verwenden möchten. In diesem Szenario möchten Sie das externe Listenelement mithilfe der Mitarbeiter-ID finden, klicken Sie daher unter Feld auf MitarbeiterID.
Wählen Sie den zu suchenden Wert aus. In diesem Szenario wählen Sie das Feld MitarbeiterID des aktuellen Elements aus, klicken Sie daher im Dialogfeld auf die Schaltfläche fx.
Klicken Sie in dem sich öffnenden Dialogfeld unter Datenquelle auf Aktuelles Element und unter Quellfeld auf MitarbeiterID.

Abbildung 1 zeigt das Dialogfeld zum Nachschlagen.

Abbildung 1. Dialogfeld zum Nachschlagen des Grenzwerts
Klicken Sie auf OK, um die Variable zum Nachschlagen zu erstellen.

Nachdem Sie die Variable zum Nachschlagen erstellt haben, wird eine Warnung angezeigt, ähnlich der in Abbildung 2 dargestellten. Diese Warnung wird angezeigt, da die zum Suchen des Elements in der externen Liste ausgewählte Spalte keine eindeutigen Werte enthält. In diesem Fall werden Sie von der Warnung informiert, dass das Nachschlagen den ersten Wert zurückgibt, wenn mehrere Werte gefunden werden. Diese Warnung tritt in der Regel mit externen Listenelementen auf.

Abbildung 2. Warnung beim Nachschlagen

Im nächsten Szenario wird das vorstehende Szenario dahingehend erweitert, dass Grenzwerte für bestimmte Budgetkategorien hinzugefügt werden, anstatt einen Grenzwert für alle Kostenvorlagen zu verwenden. Beispielsweise können Grenzwerte für Reisekosten bestehen, die sich von Grenzwerten für Ausstattungskosten unterscheiden. Wenn ein Mitarbeiter den Kostenbericht einreicht, überprüft der Workflow die Kategorie und deren Grenzwert, um die auszuführende Aktion zu bestimmen.

So erstellen Sie die Sandkasten-Workflowaktion

Das Codebeispiel: Beispiel für Sandkastenworkflow implementiert die in diesem Thema erläuterte Aktion. Im Allgemeinen sollte die Aktion ein Element einmal lesen und anschließend andere Eigenschaften aus dieser einen Transaktion zum externen System lesen. Darüber hinaus soll diese Aktion in Microsoft SharePoint Designer 2010 angezeigt werden, damit mehr Benutzer Workflows für die Liste schreiben können. Da SharePoint Designer keine Schleifen unterstützt, kann die Aktion keine Elementarrays zurückgeben. Stattdessen können Sie eine Aktion erstellen, die ein Element liest und deren Eigenschaften in einer XML-Zeichenfolge speichert. Anschließend wird eine weitere Aktion erstellt, um einen bestimmten Feldwert aus dieser XML-Zeichenfolge in eine SharePoint Designer-Variable zu lesen. Sie können diese Aktion optimieren, um beispielsweise nur die Werte zu speichern, die gelesen werden müssen. Dieses Beispiel soll jedoch eine möglichst allgemeine und wiederverwendbare Möglichkeit darstellen, um Eigenschaften für ein Element mit einem beliebigen Eigenschaftensatz zurückzugeben.

Die Methode mit der folgenden Signatur liest Werte aus der externen Liste.
```
public static Hashtable GetExternalListItemByField(SPUserCodeWorkflowContext context, String externalListId, string fieldName, string fieldValue)
```
Diese Methode verwendet eine externe Listen-ID und findet anschließend ein Element in dieser Liste, indem sie das erste Element sucht, das einen Feldwert für ein Feld mit dem Namen Feldname besitzt. Nachdem das Element gefunden wurde, wird jedes Feld in eine Datentabelle eingefügt und als XML gespeichert, damit diese später analysiert werden kann. Die Funktion ist allgemein genug, um auch mit SharePoint-Listenelementen verwendet werden zu können. Auf diese Weise lässt sich die Leistung verbessern, da der Finder und der spezifische Finder nur einmal aufgerufen werden und alle Eigenschaften abrufen. Der Finder wird jedoch nach wie vor aufgerufen. Sie können diese Aktion optimieren, indem der Finder nur zweimal aufgerufen wird, dies wird jedoch weiter unten in diesem Thema behandelt.
Nachdem das Element gelesen wurde, rufen Sie die Methode mit der folgenden Signatur auf, um das von dem value-Parameter festgelegte Feld nachzuschlagen.
```
public static Hashtable GetItemDataFromString(SPUserCodeWorkflowContext context, string itemData, string value) 
```
Diese Methode verwendet die XML-Zeichenfolge mit allen Elementeigenschaften im itemData-Parameter, rekonstruiert die Datentabelle und schlägt das von dem value-Parameter festgelegte Feld nach. Dies führt dazu, dass die Datentabelle bei jedem Aufruf der Funktion neu geladen wird. Dies kann jedoch wesentlich schneller erfolgen, als für jeden Aufruf das externe System abzufragen. Darüber hinaus besteht die Möglichkeit, dass der SharePoint Designer-Benutzer auswählen kann, in welchen Spalten nachgeschlagen werden soll, anstatt dies in der Methode hartzucodieren.

Die andere Datei von Interesse in dem Projekt ist die Datei elements.xml im Verzeichnis BCSWorkflowActivities. Diese Datei teilt SharePoint Designer mit, wie die Sandkastenaktion in SharePoint Designer dargestellt werden soll, und wie der Benutzer die Eigenschaften zuordnen kann. Die Details dieser Datei liegen außerhalb dieses Themas, die Datei besitzt jedoch die gleiche grundlegende Struktur wie die in Office SharePoint Designer 2007 verwendete Datei ACTIONS.xml.

So verwenden Sie das Beispiel für BCS-Sandkastenaktivitäten

Laden Sie das Beispiel für BCS-Sandkastenaktivitäten aus dem Microsoft Download Center herunter und entpacken Sie es (siehe Referenz zu SharePoint 2010: Software Development Kit.)
Öffnen Sie das Beispiel in Visual Studio 2010.
Drücken Sie F6, um die Lösung zu erstellen.
Stellen Sie die Lösung bereit.

Wenn Sie die Lösung auf einem anderen Computer bereitstellen, können Sie das in Schritt 3 erstellte Lösungspaket (WSP-Datei) verwenden und folgendermaßen vorgehen:
1. Wählen Sie in Websiteeinstellungen unter Galerien die Option Lösungen aus.
2. Laden Sie die WSP-Datei hoch, und aktivieren Sie sie.

So erstellen Sie den Workflow

Erstellen Sie in SharePoint Designer einen externen Inhaltstyp mit dem Namen SafeLimit.

Der externe Inhaltstyp sollte die folgenden sieben Felder enthalten: MitarbeiterID, Ausstattungsgrenzwert, Ausstattungsgenehmiger, Bewirtungskostengrenzwert, Bewirtungskostengenehmiger, Reisekostengrenzwert und Reisekostengenehmiger.
Erstellen Sie eine externe Liste für den externen Inhaltstyp Grenzwert, und benennen Sie diese mit Grenzwert.
Erstellen Sie eine Dokumentbibliothek für Kostenberichte, und nennen Sie sie Kostenberichte.
Fügen Sie zwei Spalten für MitarbeiterID und Kostentyp hinzu.

Kostentyp sollte ein Auswahlfeld mit den folgenden Auswahlmöglichkeiten sein: Bewirtungskosten, Ausstattung und Reisekosten.
Klicken Sie in SharePoint Designer in der Dokumentbibliothek Kostenberichte auf Neu und dann auf Listenworkflow.
Geben Sie einen Namen für den Workflow und eine Beschreibung ein, und klicken Sie dann auf Weiter.

Zu diesem Zeitpunkt befinden Sie sich im Workflow-Designer und können neue Aktionen hinzufügen.
Fügen Sie Get External List Item by Field (Sandboxed Function) ein.
1. Wählen Sie die externe Liste Grenzwerte für den ersten Parameter aus.
2. Wählen Sie die Spalte MitarbeiterID unter Verwendung von AktuellesElement für den zweiten Parameter aus, indem Sie auf die Schaltfläche fx klicken.
3. Geben Sie MitarbeiterID für den dritten Parameter ein.
4. Sie können den Ausgabeparameter unverändert lassen (dieser besitzt den Standardwert ItemString).
Um eine Datenspalte aus dem in ItemString gespeicherten Element zu lesen, fügen Sie Read External List Item Data (Sandboxed Function) hinzu.
1. Geben Sie für den ersten Parameter ein Feld ein, das angezeigt werden soll. Verwenden Sie für dieses Szenario den im Auswahlfeld Kostentyp gespeicherten Wert, und hängen Sie diesem Grenzwert an.
2. Für den zweiten Parameter wählen Sie die ItemString-Variable aus.
3. Der letzte Parameter ist der gefundene Wert, nennen Sie diesen Grenzwert.
Wiederholen Sie Schritt 8, und hängen Sie dem Wert Kostentyp den Wert Genehmiger an (anstatt von Grenzwert), und ändern Sie die Ausgabe zu Genehmiger.

Abbildung zeigt den sich ergebenden Workflow.

Abbildung 1. Sandkastenworkflow

Übliche Verwendungsszenarien für Sandkasten-Workflowaktionen

Verwenden Sie Sandkasten-Workflowaktionen für externe Listen, wenn Sie nicht über die Berechtigungen zur Bereitstellung vollständig vertrauenswürdiger Aktivitäten verfügen und eine der folgenden Aufgaben ausführen möchten:

Lesen zahlreicher Werte aus einer externen Liste
Schreiben einer einfachen Funktion, die mit SharePoint-Listen und externen Listen verwendbar ist

Tipps für die Verwendung von Sandkasten-Workflowaktionen

Sandkasten-Workflowaktionen können zu einem Fehler in Ihrem Workflow führen, wenn dieser keine Anwendungsdomäne für den Sandkasten-Arbeitsprozess abrufen kann. Die Anzahl der von einem Administrator konfigurierten Anwendungsdomänen ist unveränderlich, und die Anwendungsdomänen werden vom gesamten Sandkastencode gemeinsam verwendet, z. B. von Aktionen, Webparts und Ereignisempfängern. Seien Sie daher vorsichtig, wenn Sie Sandkastenaktionen in den folgenden Situationen verwenden:

Komplexe Sandkastencode-Aktionen, die einige Zeit in Anspruch nehmen
Langsame externe Listen
Eine Umgebung, in der zahlreiche Workflows in etwa zur gleichen Zeit ausgeführt werden
Szenarien, die keine Workflowfehler verarbeiten können

Der Sandkasten-Codedienst kann diese Aufrufe mit einem Konto ausführen, das sich vom Anwendungspoolkonto unterscheidet, Sie müssen daher sicherstellen, dass dieses Konto in Einmaliges Anmelden eingerichtet ist.

Wenn Sie eine lokale Kopie der Daten speichern, die Sie aus einem externen Listenelement gelesen haben, wie in diesem Beispiel, müssen Sie sicherstellen, dass Ihre Daten aktuell sind.