Tutorial: Mit SharePoint Webservices arbeiten

Transcription

Tutorial:
Mit SharePoint Webservices arbeiten
Version: 0.1
Autor: Anja Beuth
Inhaltsverzeichnis
1
2
2.1
2.2
2.3
2.3.1
2.3.2
3
3.1
3.1.1
4
4.1
4.2
4.3
Überblick......................................................................................................... 3
Extension erweitern......................................................................................... 3
Webverweis hinzufügen.................................................................................. 3
Code erweitern................................................................................................ 5
Fehlerquellen.................................................................................................. 7
Webservice nicht erreichbar............................................................................ 7
Login am Webserver funktioniert nicht............................................................ 7
Transformationen erweitern............................................................................. 7
Fehlerquellen.................................................................................................. 9
Listenadressierung.......................................................................................... 9
Authentifizierung auslagern............................................................................. 9
web.config anpassen....................................................................................... 10
Modul erweitern............................................................................................... 10
Extension erweitern......................................................................................... 11
Voraussetzungen
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
Beschreibung
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.
Zeichenerklärung
Text, der grün umrandet und mit dem Pfeil-Symbol gekennzeichnet ist, enthält
konkrete Anweisungen, was als nächstes zu tun ist.
Texte in solchen Kästchen enthalten Tipps und Tricks.
1
Quellcode wird in solch blauen Boxen dargestellt.
2
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
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 »http://<Site>/_vti_bin/Lists.asmx«) und vergeben Sie einen Namen,
z.B. "SharepointLists".
4
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
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
= "http://www.my-sharepoint.de/_vti_bin/lists.asmx";
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
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
2.3.1 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.
2.3.2 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.
Die Webservice-Methode "UpdateListItems()" benötigt wie gesagt ein XML-Element und
die GUID der SharePoint-Liste, auf die zugegriffen werden soll.
7
Achtung: Hiermit ist nicht der XLink gemeint, sondern wirklich nur die GUID!
X
L
i
n
k
:
sharepoint://list(en,064525c1-007a-47a6-b349-32990e2416ad)@189b38e1-5b2a-49a6-aefd-b601a26e0bee
GUID: 064525c1-007a-47a6-b349-32990e2416ad
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">2012-04-05 13: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-b349-32990e2416ad">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-b349-32990e2416ad,11)@189b38e1-5b2a-49a6-aefd-b601a26e0bee«
lässt sich ermitteln, dass der Eintrag innerhalb der Liste die ID »11« hat.
8
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
3.1.1 Listenadressierung
Achten
Sie
darauf,
dass
Sie
wirklich
nur
die
Listen-GUID
(z.B.
»064525c1-007a-47a6-b349-32990e2416ad«) angeben, nicht den XLink (z.B.
»sharepoint://list(en,064525c1-007a-47a6-b349-32990e2416ad)@189b38e1-5b2a-49a6-aefd-b601a26e0bee«).
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
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="http://www.my-sharepoint.de"
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
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 + @"/_vti_bin/lists.asmx";
}
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

Tutorial: Mit SharePoint Webservices arbeiten

Transcription

Documents pareils

PDF-Anbieterübersicht "SharePoint"

wissensmanagement - Anbieterübersicht Sharepoint APPS 2013

Lebenslauf Igor Galochkin

Die Terminologie der Technischen Dokumentation steigert den

Case Studie: SharePoint-basiertes ICD-10 Diagnose

Wie Ihr SharePoint-Projekt zum Erfolg wird

Webservices - Department of Information Systems

TCTM Case Study - ATE

Allgemeine Geschäfts Bedingungen