Tutorial: Mit SharePoint Webservices arbeiten. version: 0.1 Author: Anja Beuth

Transkript

1 Tutorial: Mit SharePoint Webservices arbeiten version: 0.1 Author: Anja Beuth

2 Table of contents Überblick... Extension erweitern... Webverweis hinzufügen... Code erweitern... Fehlerquellen... Webservice nicht erreichbar... Login am Webserver funktioniert nicht... Transformationen erweitern... Fehlerquellen... Listenadressierung... Authentifizierung auslagern... web.config anpassen... Modul erweitern... Extension erweitern

3 Requirements Der Entwickler benötigt für dieses Tutorial vollen Webserver-Zugriff. Außerdem muss Administrator-Zugriff auf den SharePoint Server bzw. auf die SharePoint Installation vorhanden sein. Da für die Nutzung der SharePoint Webservices auch Änderungen in SharePoint vorgenommen werden müssen, sollten Kenntnisse im Umgang mit der Software vorhanden sein. Darüber hinaus sollte der Entwickler sich bereits mit der onion.net SharePoint Integration auseinandergesetzt haben. Für die grundsätzliche Durchführung wird voraugesetzt, dass im vorliegenden Projekt bereits ein eigenes Modul bzw. eine eigene Extension eingebunden ist. Darüber hinaus wird vorausgesetzt, dass die SharePoint Integration korrekt installiert wurde und funktioniert. Dieses Tutorial gibt keine allgemeine Einführung in SharePoint, SharePoint Webservices, die onion.net SharePoint Integration oder die Extension-Entwicklung. Eigene Module und Extensions entwickeln Übersicht über die vorhandenen SharePoint Webservices Microsoft Anleitungs-Seite zu SharePoint Description Dieses Tutorial beschreibt die Verwendung von SharePoint Webservices am Beispiel der Methode "UpdateListItems". Mit dieser Methode können Listen-Elemente in einer SharePoint-Liste gelöscht oder aktualisiert werden. Außerdem ist das Hinzufügen von neuen Elementen möglich. In diesem Tutorial werden Werte aus den Transformationen heraus mit Hilfe der WebServices als Listen-Element einer SharePoint Liste abgespeichert. Signs and symbols Boxes marked with an arrow symbol and a green border contains instruction of what to do next. This kind of boxes contains tips and tricks. 1

4 Source code is shown in blue boxes. 2

5 1 Überblick 1 Überblick Der Ablauf wird später so sein, dass in den Transformationen eine Extension-Methode aufgerufen wird. Dabei wird bereits das XML übergeben, was der Webservice später benötigt. Die Extension-Methode stellt sozusagen nur den Vermittler zwischen Transformationen und Webservice dar. Sie stellt die Verbindung zum Webservice her und ruft die Methode mit den entsprechenden Parametern auf. Anschließend werden eventuelle Fehler geloggt und eine entsprechende Rückmeldung in Form des Textes "success" oder "error" zurück gegeben, die dann in den Transformationen entsprechend behandelt werden können. Der Webservice wirft im Falle eines Fehlers lediglich eine Exception vom Typ»Microsoft.SharePoint.SoapServer.SoapServerException«. Dies ist nicht sehr aussagekräftig. In manchen Fällen wird auch keine Exception geworfen, sondern lediglich im Rückgabe-XML des Webservices auf einen Fehlercode verwiesen. Daher folgt jedem Teil dieses Tutorials ein Abschnitt "Fehlerquellen", der die häufigsten Probleme und Lösungen bereitstellt. Diese Abschnitte sind nicht abschließend und werden ggf. stetig erweitert. 2 Extension erweitern Da wir für die Erweiterung der Transformationen schon genau wissen müssen, was die Webservice-Methode erwartet, bietet es sich an, zunächst die Extension-Methode zu erstellen, und sich ein wenig mit dem Webservice vertraut zu machen. 2.1 Webverweis hinzufügen Um im Visual Studio die Methoden eines Webservices nutzen zu können, muss dieser als Verweis hinzugefügt werden. Rechtsklicken Sie auf das Projekt und wählen Sie "Webverweis hinzufügen". 3

6 2 Extension erweitern Wenn Sie diesen Eintrag nicht im Kontextmenü haben, wählen Sie stattdessen "Dienstverweis hinzufügen". Im sich öffnenden Dialog Klicken Sie auf "Erweitert..." und wählen dort "Webverweis hinzufügen". Tragen Sie in dem sich öffnenden Dialog die URL zum Webservice ein (in unserem Fall» und vergeben Sie einen Namen, z.b. "SharepointLists". 4

7 2 Extension erweitern Wenn Sie auf den grünen Pfeil klicken, werden die vorhandenen Methoden aufgelistet. Nachdem Sie auf "Verweis hinzufügen" geklickt haben, sollte der Websevice im Projektmappen-Explorer wie folgt angezeigt werden. 2.2 Code erweitern Um die Methoden des Webservices nutzen zu können, muss zunächst eine entsprechende Instanz vorhanden sein. Fügen Sie zunächst die Klasse des gerade eingefügten Webservices zur Verwendung mit der using-direktive ein. using Contoso.Renderengine.SharepointLists; 5

8 2 Extension erweitern Dann können wir ein globales Objekt darauf erstellen: private Lists lists = new Lists(); Da SharePoint mit dem Active Directory der Domäne verknüpft ist, ist in der Regel eine Anmeldung vonnöten. Erweitern Sie den Konstruktor der Extension um folgenden Code: lists.credentials = new NetworkCredential("username", "password");lists.url = " Wenn SharePoint auf einem anderen Server läuft als die Render Engine und die Anmeldedaten ein anderen Domäne zugeordnet sind, muss diese als dritter Parameter beim Erzeugen der NetworCredentials übergeben werden. Achtung: Dabei muss immer das Protokoll vorangestellt werden (auch wenn statt einer lesbaren URL eine IP-Adresse angegeben wird). Nun können wir eine Extension-Methode hinzufügen, die als der gewünschte Vermittler gilt. Fügen Sie dazu folgenden Code hinzu. [ExtensionMethod(Name = "updatelistitems")] public string UpdateListItems(string listid, XPathNavigator batchxml) { try { XmlDocument batch = new XmlDocument(); batch.loadxml(batchxml.innerxml); XmlNode updates = batch.selectsinglenode("batch"); lists.updatelistitems(listid, updates); return "success"; } 6

9 3 Transformationen erweitern catch (Exception e) { Log.Error(e.Message); return "error"; } } Wir wollen die Webservice-Methode "UpdateListItems()" verwenden. Diese ist in der Microsoft Library dokumentiert. Die Methode ist für die drei Anwendungsfälle Löschen, Aktualisieren und Hinzufügen universell verwendbar. Was genau gemacht werden soll, wird über das "Batch"-XML gesteuert, welches als Parameter übergeben wird. Das sehen wir uns im nächsten Abschnitt an, da wir es in den Transformationen erstellen wollen. Bauen Sie im Anschluss daran ein neues Build und aktualisieren Sie die onion.net Render Engine. 2.3 Fehlerquellen Webservice nicht erreichbar Rufen Sie die URL des Webservices lokal im Browser auf. Wenn Sie (ggf. nach einem Login) die Methoden des Webservices aufgelistet bekommen wissen Sie, dass der Webservice erreichbar ist. Bekommen Sie die Methoden nicht aufgelistet, obwohl die Anmeldung und die URL korrekt sind, muss ggf. in SharePoint noch eine Einstellung nachgezogen oder auf dem Server ein Port in der Firewall für die Webservices geöffnet werden Login am Webserver funktioniert nicht Prüfen Sie, ob Sie die korrekte Domäne bei der Erzeugung der NetworkCredentials angegeben haben und ob das Protokoll (z.b. "http") vorangestellt ist. Dies muss auch dann mit angegeben werden, wenn Sie keine lesbare Webadresse, sondern nur eine IP-Adresse angeben. 3 Transformationen erweitern Die Webservice-Methode "UpdateListItems()" benötigt wie gesagt ein XML-Element und die GUID der SharePoint-Liste, auf die zugegriffen werden soll. 7

10 3 Transformationen erweitern Achtung: Hiermit ist nicht der XLink gemeint, sondern wirklich nur die GUID! X L i n k : sharepoint://list(en,064525c1-007a-47a6-b e2416ad)@189b38e1-5b2a-49a6-aefd-b601a26e0bee GUID: c1-007a-47a6-b e2416ad In der Microsoft Library ist der mögliche Aufbau des Batch-XMLs ausführlich dokumentiert. Im Falle einer Produktbewertung könnte es beispielsweise so aussehen: <Batch OnError="Continue"> <Method ID="1" Cmd="New"> <Field Name="ID">New</Field> <Field Name="Title"> :42 Erika Mustermann</Field> <Field Name="FullName">Erika Mustermann</Field> <Field Name="Bewertung">5</Field> <Field Name="Bewertungstext">Super Produkt! Jederzeit wieder! Nur zu empfehlen!</field> </Method> </Batch> Die Felder "FullName", "Bewertung" und "Bewertungstext" sind dabei selbst hinzugefügte Webseitenspalten am Datentyp des Listen-Elements. Als Attribut "Name" muss hier der SharePoint-interne Name angegeben werden. Dieser kann in SharePoint selbst ermittelt werden. Eine Alternative ist die onion.net-datensicht auf SharePoint-Inhalte. Wenn Sie eine Websitespalte vom Typ "Lookup" mittels des Batch-XML befüllen wollen, müssen Sie dies nach folgenden Schema aufbauen. <Field Name="ProductReference" List="{List-GUID der Referenzliste}">{Listen-ID des jew. Eintrags in der Referenzliste}</Field> also konkret zum Beispiel: <Field Name="ProductReference" List="064525c1-007a-47a6-b e2416ad">10</Field> Die Listen-ID des Eintrags ist dabei die eindeutige Nummer des Listeneintrags, auf den verwiesen werden soll, innerhalb der Liste, in der sich der Eintrag befindet. Diese findet sich im XLink eines Listeneintrags. Für den XLink»sharepoint://listitem(en,064525c1-007a-47a6-b e2416ad,11)@189b38e1-5b2a-49a6-aefd-b601a26e0bee«lässt sich ermitteln, dass der Eintrag innerhalb der Liste die ID»11«hat. 8

11 4 Authentifizierung auslagern Erzeugen Sie in SharePoint manuell einen Listeneintrag und rufen Sie im Browser das XML des Eintrags mit der Datensicht "content" auf. 3.1 Fehlerquellen Listenadressierung Achten Sie darauf, dass Sie wirklich nur die Listen-GUID (z.b.»064525c1-007a-47a6-b e2416ad«) angeben, nicht den XLink 4 Authentifizierung auslagern Momentan befinden sich die Informationen für den Verbindungsaufbau zum SharePoint noch direkt in unserer Extension. Dies ist aus verschiedenen Gründen nicht sehr sinnvoll. Zum Einen macht es den Code nicht wiederverwendbar. Wenn beispielsweise in der Vorschau ein anderes SharePoint genutzt werden soll, als Live (um in der Vorschau produzierte Tests nicht in das produktive SharePoint einfließen zu lassen), so ist dies nicht ohne weiteres möglich. Es müsste unterschiedliche Extensions oder unterschiedliche Extension-Methoden für Live und Preview geben. Darüber hinaus würde eine Änderung der Zugangsdaten, die vielleicht aus Sicherheitsgründen periodisch alle 3 Monate durchgeführt wird, oder der Umzug des SharePoint-Systems auf einen anderen Server mit anderer IP-Adresse eine unnötige Änderung in der Extension bedeuten. Anstatt den Server-Administrator seine administrativen Tätigkeiten durchführen zu lassen, muss ein Web-Entwickler eine Änderung im Code durchführen und die Render Engines aktualisieren. Letzteres bringt in der Regel einen Neustart der Webanwendung mit sich, was im laufenden Betrieb vielleicht nicht zu jeder Tageszeit erwünscht ist. Daher wollen wir die Anmeldeinformationen in die web.config-datei der Render Engine auslagern. Spätestens jetzt sollten Sie einen speziellen onion.net-benutzer anlegen, der keinen administrativen Zugriff auf das SharePoint hat, da der Zugang ja nun mehr oder weniger für "jedermann" offengelegt wird, der Zugriff auf die web.config hat. 9

12 4 Authentifizierung auslagern 4.1 web.config anpassen Zunächst wollen wir die Anmeldeinformationen in die web.config einfügen. Ähnlich der Konfiguration der ImageServer legen wir dafür ein Element unterhalb der Modulkonfiguration an. Erweitern Sie die Konfiguration des Projekt-Moduls wie folgt. <module type="{projektname}.renderengine.{projektname}module, {Projektname}.Renderengine"> <sharepoint uri=" username="username" password="password" /> </module> Wenn benötigt kann auch noch ein Attribut "domain" mit dem entsprechenden Wert angehangen werden. 4.2 Modul erweitern Im Modul kann auf die Konfiguration zugegriffen werden. Der Methode "Configure()" wird als zweiter Parameter ein XMLElement "configuration" übergeben. Dies enthält alles XML, welches in der Konfiguration innerhalb des <module>-elements aufgeführt wird. In unserem Fall also das <sharepoint>-element. Wir wollen nun die Attribute unseres neuen Elements <sharepoint> auslesen und an die Extension übergeben, um sie dort für den Verbindungsaufbau zu verwenden. Erweitern Sie die Methode Configure() der Klasse "{Projektname}Module" um folgenden Code. XmlElement sp = configuration["sharepoint"]; if (sp == null) throw new ConfigurationException("Element 'sharepoint' ist missing", configuration); string uri = sp.getattribute("uri"); string username = sp.getattribute("username"); string pw = sp.getattribute("password"); string domain = sp.getattribute("domain"); if (String.IsNullOrEmpty(uri) String.IsNullOrEmpty(username) String.IsNullOrEmpty(pw)) throw new ConfigurationException("Sharepoint configuration is not correct.", configuration); extensions = new ContosoExtension(uri, username, pw, domain); 10

13 4 Authentifizierung auslagern Zunächst greifen wir konkret auf das <sharepoint>-element zu. Wenn es nicht da sein sollte, wird eine entsprechende Exception geworfen. Im Anschluss daran werden die entsprechenden Attribute ausgelesen und in Variablen gespeichert. Auch hier werden wieder die benötigten Werte zunächst überprüft und gegebenenfalls eine Exception geworfen. Zu guter Letzt werden die Werte beim Erzeugen der Extension mit übergeben. Sie können auch statt der Exceptions einfach einen entsprechenden Fehler loggen, falls die Website auch ohne eine korrekte Sharepoint-Anbindung funktionieren soll. 4.3 Extension erweitern Die übergebenen Parameter müssen nun im Konstruktur der Extension entgegen genommen werden. Erweitern / Verändern Sie den Konstruktor der Extension wie folgt. public ContosoExtension(string uri, string username, string password, string domain) { lists.credentials =!String.IsNullOrEmpty(domain)? new NetworkCredential(username, password, domain) : new NetworkCredential(username, password); lists.url = uri } In Abhängigkeit davon, ob eine Domain übergeben wird, werden die NetworkCredentials mit oder ohne diese Domain erzeugt. Die "uri" wird verwendet, um die korrekt URL für den Zugriff auf den Webservice festzulegen. 11