Exemplarische Vorgehensweise: Verwenden von voll vertrauenswürdigen SharePoint-Workflowaktivitäten mit Business Connectivity Services

In dieser exemplarischen Vorgehensweise wird veranschaulicht, wie Sie eine voll vertrauenswürdige Aktivität für einen Workflow erstellen, der Microsoft Business Connectivity Services (BCS) verwendet. Dieses Beispiel beinhaltet ein einfaches Spesengenehmigungsszenario, bei dem mit einem Workflow die Genehmigungsgrenzwerte und sicheren Grenzwerte mithilfe von Business-Konnektivitätsdienste (Business Connectivity Services) aus dem externen System abgerufen werden. Diese Werte entsprechen dem jeweiligen Mitarbeiter (angegeben mittels einer Mitarbeiter-ID) und dem Spesentyp.

Letzte Änderung: Freitag, 16. Juli 2010

Gilt für: SharePoint Server 2010

Diese exemplarische Vorgehensweise basiert auf dem Beispiel "BCS Full-Trust Workflow Activity", das im Microsoft SharePoint 2010 Software Development Kit (SDK) enthalten ist. Weitere Informationen zum Herunterladen dieses Beispiels finden Sie unter Codebeispiel: BCS Full-Trust Activity Workflow.

Voll vertrauenswürdige Aktivitäten werden in Microsoft Visual Studio erstellt und erfordern Folgendes:

• Installation im globalen Assemblycache.

• Eine .actions-Datei im Workflowvorlagenordner im Dateisystem jedes Farmservers.

• Einen Eintrag AuthorizedTypes in der Datei web.config auf jedem Server, damit die Assembly ausgeführt werden kann. Diese müssen auf jedem Farmserver bereitgestellt werden und erfordern deshalb wesentlich höhere Berechtigungen und mehr Überwachung.

Tipps zur Verwendung von BCS-Aktionen und häufige Fehler

Verwenden sie voll vertrauenswürdige Workflowaktivitäten für Business-Konnektivitätsdienste (Business Connectivity Services) in folgenden Fällen:

• Sie sind berechtigt, voll vertrauenswürdige Aktivitäten bereitzustellen.

• Sie möchten eine der folgenden Aktionen ausführen:

  • Lesen, Erstellen und Aktualisieren von Daten in einem externen System über einen Workflow mit oder ohne Bereitstellung einer externen Liste.

  • Ausführen von möglichst wenigen Aufrufen für das externe System.

  • Verwenden komplexer Logik, die Schleifen für mehrere Elemente oder Zuordnungen mit anderen externen Inhaltstypen erfordert, ohne den Sandkasten-Codedienst zu verwenden.

Beachten Sie bei der Verwendung voll vertrauenswürdiger Workflowaktivitäten Folgendes:

• Voll vertrauenswürdige Aktivitäten werden, wie bereits ihr Name besagt, als voll vertrauenswürdig ausgeführt. Dies bedeutet, dass Sie vor der Bereitstellung der Aktivität genau wissen sollten, was die Aktivität bewirkt, und dass Sie dem Autor der Aktivität vertrauen sollten, so als ob es sich bei diesem Autor um einen Administrator handeln würde.

• Falls Sie diese Aktivität in Microsoft SharePoint Designer verwenden, müssen Sie eine festgelegte Anzahl von Elementen zurückgeben, da Schleifen von SharePoint Designer nicht unterstützt werden.

Erstellen der voll vertrauenswürdigen Workflowaktivität

Mit der Aktivität, die Sie in diesem Thema erstellen, werden die genehmigende Person und ein sicherer Grenzwert für einen bestimmten Spesentyp und eine bestimmte Mitarbeiter-ID zurückgegeben. Informationen zum externen Inhaltstyp sind bereits in die Aktivität integriert, und die Aktivität kann nur für diesen externen Inhaltstyp ausgeführt werden.

Erstellen der Workflowaktivität

In dieser exemplarischen Vorgehensweise wird dasselbe Szenario verwendet wie in Vorgehensweise: Erstellen von Sandkasten-Workflowaktionen. Hier verwenden Sie zur Erreichung Ihrer Ziele jedoch keine externe Liste, sondern lediglich die Business Data Connectivity-Dienst (BDC)-APIs. Dies ist etwas komplexer als das bloße Lesen eines Elements in einer Liste, da die BDC-APIs im Vergleich zu einer flachen Liste wesentlich flexibler sind. Bevor wir uns mit dem Code befassen, sollten Sie die durch diese Aktivität verfügbar gemachten Eigenschaften kennen. Alle Eigenschaften der Aktivität werden zwar so verfügbar gemacht, dass sie in SharePoint Designer bearbeitet werden können, aber es gibt einige integrierte Standardwerte. Sie müssen deshalb keine Informationen für jene Werte eingeben, die zwischen Bereitstellungen einheitlich sein sollten.

Tabelle 1. Eigenschaften für Beispielworkflowaktivität

Zum besseren Verständnis dieses Beispiels sollten Sie den Aktivitätscode in BDCReadActivity.cs betrachten. Beachten Sie, dass der gesamte Code in der Execute-Methode enthalten ist, die vom Workflowhost zum Ausführen der Aktivität aufgerufen wird. Bei diesem Aufruf wird wie im folgenden Code dargestellt in der ersten BDC-Aktion der Metadatenspeicher abgerufen, der den externen Inhaltstyp SafeLimits enthält.

private IMetadataCatalog GetMetadataCatalog(SPSite site, ISharePointService hostInterface)

Sie sollten einige Punkte beachten, auch wenn der Code auf den ersten Blick einfach aussieht. Zum einen gilt der Katalog nicht für eine Website, sondern für eine Farm. Dies bedeutet, dass diese Aktivität für jede Website verwendet werden kann, die denselben BDC-Dienst verwendet. Zum zweiten geben die zum Abrufen des Metadatenspeichers verwendeten SharePoint-APIs NULL zurück, wenn das Element nicht gefunden wird. Dies ist ein Unterschied zu den BDC-APIs, die Ausnahmen auslösen, wenn Elemente nicht gefunden werden.

Nachdem nun der Metadatenspeicher vorhanden ist, müssen Sie wie im folgenden Methodenbeispiel veranschaulicht den externen Inhaltstyp suchen und die richtigen Daten zurückgeben.

private void GetSafeLimits(IMetadataCatalog catalog, ISharePointService hostInterface)

Beachten Sie bei dem Codebeispiel, dass sich GetEntity in einem try/catch-Block befindet. Wenn deshalb der externe Inhaltstyp gelöscht wird oder nicht in diesem Katalog vorhanden ist, wird eine MetadataObjectNotFoundException-Ausnahme ausgelöst. Zur Behandlung dieser Ausnahme fügen Sie in der Workflowverlaufsliste einen Eintrag hinzu, um Sie über die Ausnahme zu informieren, und lösen Sie die Ausnahme erneut aus, damit der Workflow fehlschlagen kann.

Nun da der externe Inhaltstyp vorhanden ist, müssen Sie nach einer bestimmten Instanz dieses externen Inhaltstyps suchen. Verwenden Sie dazu die FindSpecific-Methode von IEntity. Diese Methode akzeptiert zwei Parameter. Der erste Parameter ist die Identity der spezifischen Instanz. In diesem Beispiel wurde EmployeeID als Bezeichner festgelegt, weshalb EmployeeID als Identity übergeben werden muss. Sie sehen an diesem Punkt, wie spezifisch die Identität für den externen Inhaltstyp ist. Ein anderer externer Inhaltstyp könnte einen anderen Bezeichner mit einem anderen Namen und sogar einem anderen Typ aufweisen. Der zweite Parameter ist die externe Systeminstanz, die wir bei der Suche nach dem Element verwenden. Wie bereits zuvor erwähnt, ist nur eine externe Systeminstanz vorhanden, da Sie SharePoint Designer verwenden, und Sie verwenden den im Code dafür gespeicherten Namen. Sie sollten auch beachten, dass FindSpecific eine andere Ausnahme auslöst, wenn das Element nicht gefunden wird: ObjectNotFoundException. Sie möchten wiederum diese Ausnahme erfassen und dem Benutzer eine aussagekräftige Fehlermeldung anzeigen, bevor die Ausnahme erneut ausgelöst wird, damit der Workflow fehlschlagen kann. Nachdem nun die Entitätsinstanz vorhanden ist, sind die restlichen Schritte ganz einfach. Mithilfe der Feldnamen in eckigen Klammern können Sie die Werte der Instanz abrufen.

Mit den folgenden Schritten wird ein Workflow basierend auf dem Beispiel "BCS Full-Trust Workflow Activity" erstellt.

So richten Sie das Beispiel ein

1. Führen Sie die Schritte unter Codebeispiel: BCS Full-Trust Activity Workflow aus, um das Beispiel "BCS Full-Trust Workflow Activity" herunterzuladen und zu installieren.

2. Erstellen Sie in SharePoint Designer einen externen Inhaltstyp mit dem Namen SafeLimits, mit dem Namespace BCSBlog, und eine externe Systeminstanz mit dem Namen SafeLimit. Beachten Sie, dass diese Werte im Beispielaktivitätscode hartcodiert sind. Stellen Sie außerdem sicher, dass der externe Inhaltstyp die folgenden sieben Felder aufweist: EmployeeID, EquipmentLimit, EquipmentApprover, MoraleLimit, MoraleApprover, TravelLimit und TravelApprover.

   Hinweis
   Sie müssen ein externes System, wie z. B. eine Datenbank, mit einer Datenstruktur einrichten, die die hier aufgelisteten Felder enthält.

3. (Optional) Sie können eine externe Liste erstellen, um den externen Inhaltstyp zu überprüfen.

4. Öffnen Sie die Projektmappe in Visual Studio 2010.

5. Erstellen Sie die Projektmappe.

   Das Ergebnis ist die Datei BCSReadActivity.dll, die im globalen Assemblycache des Front-End-Webserver bereitgestellt wird (%windir%\assembly), damit die Aktivität von SharePoint Server gefunden und geladen werden kann.

   Stellen Sie vor dem Erstellen der Projektmappe sicher, dass die Standardwerte für EntityName, EntityNamespace, und LobSystemInstanceName entsprechend Ihrer Einstellung aktualisiert werden. Diese Standardwerte sind in der GetSafeLimits-Methode definiert.

6. Stellen Sie die Projektmappe bereit.

   1. Fügen Sie die Assembly der Datei web.config auf jedem SharePoint-Farmserver hinzu.

      1. Öffnen Sie die Datei web.config Ihrer SharePoint-Website auf dem Farmserver.

      2. Suchen Sie im unteren Abschnitt nach <System.Workflow.ComponentModel.WorkflowCompiler>. Innerhalb dieses Tags sollte der Abschnitt <authorizedTypes> und ein Eintrag für jede Typgruppe vorhanden sein. Fügen Sie die folgende Zeile hinzu (achten Sie darauf, dass die Typinformationen stimmen, einschließlich des öffentlichen Schlüsseltokens).

         <authorizedType Assembly="BCSReadActivity, Version=1.0.0.0, Culture=neutral, PublicKeyToken=90f597110ccda6ac" Namespace="Microsoft.SharePoint.Samples" TypeName="SafeLimitActivity" Authorized="True" />
         

   2. Stellen Sie die Datei BCSReadActivity.ACTIONS auf jedem SharePoint-Farmserver bereit.

      1. Kopieren Sie auf jedem Farmserver BCSReadActivity.ACTIONS in den folgenden Ordner des SharePoint-Serverinstallationsordners: %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\template\1033\workflow.

         Hinweis
         1033 ist die Gebietsschema-ID (Locale ID, LCID) für das US-englische Gebietsschema. Der Name dieses Ordners ändert sich entsprechend, falls Sie ein anderes Gebietsschema verwenden.

      2. Führen Sie den Befehl iisreset auf jedem Farmserver aus.

So erstellen Sie den Workflow

1. Erstellen Sie eine Dokumentbibliothek für Spesenabrechnungen, und nennen Sie sie ExpenseReports.

2. Fügen Sie die folgenden Spalten hinzu:

   • EmployeeID

   • ExpenseType als Auswahlfeld mit den folgenden Optionen: Morale, Equipment, Travel

   • Approver

   • Limit

3. Klicken Sie in SharePoint Designer in der Dokumentbibliothek ExpenseReports auf Neuer Listenworkflow.

4. Benennen Sie den Workflow, und geben Sie eine Beschreibung ein. Klicken Sie anschließend auf OK.

   Hinweis
   Nun arbeiten Sie im Workflow-Designer und können mit dem Hinzufügen Ihrer Aktionen beginnen.

5. Fügen Sie die Aktion Get Safe Limits for Employee ein.

   1. Lassen Sie die ersten beiden Parameter unverändert. Dies sind die Ausgabevariablen aus der Funktion für Approver und SafeLimit.

   2. Geben Sie für den dritten Parameter den Wert für Category an. Dies ist bereits in Ihrer Liste definiert. Wählen Sie also wie zuvor die ExpenseType-Spalte aus. Verwenden Sie dazu CurrentItem und die Funktionsschaltfläche (fx).

   3. Für den letzten Parameter wählen Sie die EmployeeID-Spalte aus. Verwenden Sie dazu CurrentItem und die Funktionsschaltfläche (fx).

      Nun sollte wie in Abbildung 1 dargestellt ein neuer Listenworkflow angezeigt werden.

      Abbildung 1. Neuer Listenworkflow in Microsoft SharePoint Designer

      

6. Fügen Sie eine weitere Aktion zum Schreiben der Ausgabevariablen aus der Funktion für Approver und SafeLimit hinzu.

   1. Fügen Sie die Aktion Listenelement aktualisieren hinzu.

   2. Klicken Sie auf die Verknüpfung Diese Liste.

   3. Klicken Sie auf Hinzufügen, und wählen Sie dann Approver aus.

   4. Klicken Sie im Dialogfeld Nachschlagen für eine Textzeile auf die Schaltfläche fx.

   5. Wählen Sie für Datenquelle die Option Workflowvariablen und -parameter aus.

   6. Wählen Sie für Quellenfeld die Option Variable: Approver aus.

   7. Schließen Sie das Dialogfeld.

   8. Wiederholen Sie die Schritte c bis g, um die Variable für SafeLimit hinzuzufügen.

7. Speichern Sie den Workflow, und veröffentlichen Sie ihn.

Hinweis

Stellen Sie vor dem Ausführen des Workflows sicher, dass Sie in Ihrem BDC-Modell entsprechende Berechtigungen für das externe System und den externen Inhaltstyp eingerichtet haben, damit der Workflow auf diese Ressourcen zugreifen kann. Darüber hinaus wird empfohlen, Einmaliges Anmelden als Authentifizierungstyp für das BDC-Modell zu verwenden. Weitere Information zu Workflows in Business-Konnektivitätsdienste (Business Connectivity Services) finden Sie unter Gewusst wie: Verwenden von Business Connectivity Services mit SharePoint-Workflows.

So führen Sie den Workflow aus

1. Füllen Sie Ihr externes System mit Daten auf.

2. Erstellen Sie ein Element in der ExpenseReports-Dokumentbibliothek. Stellen Sie sicher, dass die hinzugefügten Werte für die Mitarbeiter-ID und den Spesentyp im externen System vorhanden sind.

3. Lösen Sie den Workflow aus.

   Die Felder Approver und SafeLimit im Dokumentbibliothekseintrag sollten vom Workflow mit Werten aus dem externen System aufgefüllt werden.