Communardo Software GmbH, Kleiststraße 10 a, D-01129 Dresden
0800 1 255 255

JSOM im produktiven Einsatz – die definitive Liste getesteter Operationen

Sie möchten eine SharePoint-hosted App entwickeln, sind sich aber nach der Lektüre meines letzten Beitrags nicht sicher, ob sich mittels JavaScript Object Model (JSOM) alle Anforderungen abbilden lassen (Stichwort: „JSOM-Limitierungen“)?

Wir haben den Sprung gewagt und SharePoint-hosted Apps als Vorlage eingesetzt. Dabei haben wir die Möglichkeiten und Grenzen von JSOM kennengelernt.

Dieser Beitrag zeigt, welche JSOM-Operationen produktiv erfolgreich eingesetzt wurden und wo es Probleme gab.

JSOM als Unbekannte

Eigentlich ganz einfach: JSOM ist vergleichbar mit CSOM und stellt ein Subset der SharePoint Server-API (SSOM) clientseitig zur Verfügung.

Nur in JavaScript. Und asynchron. Und weniger dokumentiert.

Also doch nicht einfach. Die genannten Punkte reichen bereits, um einen Zeitplan ins Wanken zu bringen. Dazu kommt die Unsicherheit, ob sich alle Anforderungen mit JSOM abbilden lassen.

Eine Liste häufig genutzter API-Funktionen ist zwar hilfreich, doch selbst wenn sie vollständig wäre, würden die Zusammenhänge fehlen. Darüberhinaus bleibt immer der Zweifel, ob in der Praxis funktioniert, was die Dokumentation verspricht.

Was fehlt, ist eine Zusammenstellung von JSOM-Operationen, die tatsächlich in der Praxis getestet wurden.

Liste getesteter JSOM-Operationen

Den Zweifel, welche Anforderungen sich mittels JSOM abbilden lassen, möchte ich helfen auszuräumen.

Es folgt eine Zusammenstellung der Operationen, die in der Praxis getestet wurden sowie Hinweise auf mögliche Probleme. Problematische Operationen sind gelb oder rot gekennzeichnet und mit entsprechenden Bemerkungen versehen.

Arbeit mit Listen

Operation   Bemerkungen
Listen enumerieren   Beispiel
Liste erstellen  

Beispiel

einzelne Spalten können direkt per XML-Definition übergeben werden

Liste verändern   Beispiel
Liste löschen   Beispiel 
Listenelemente enumerieren   Beispiel
Listenelement anlegen   Beispiel
Listenelement verändern   Beispiel 
Listenelement löschen   Beispiel

Arbeit mit Listen-Ansichten (Views)

Operation   Bemerkungen
Views enumerieren   Beispiel
View erstellen    
Bestehenden View verändern  

Beispiel

View-Query-Definition wird als XML übergeben; View-Spalten können einzeln angegeben werden

View als Standardview festlegen    

Arbeit mit Dokumentenbibliotheken

Operation   Bemerkungen
DocLibs enumerieren    
DocLib erstellen    
DocLib verändern    
DocLib löschen    
(Unter-)Ordner anlegen    
Text-Datei hochladen (Root- oder Unterverzeichnis)   muss Base64-enkodiert werden
Binär-Datei hochladen (Root- oder Unterverzeichnis)   muss Base64-enkodiert werden 1)

1) Dateien müssen Base64-enkodiert in eine Dokumentenbibliothek hochgeladen werden, was auch ohne Probleme funktioniert. Problematisch kann es sein, Binärdaten nach Base64 zu enkodieren, da die Handhabung von Binärdaten in älteren Browsern wie dem IE8 nicht gut unterstützt wird – hier fehlen oft die benötigten Datenstrukturen. In unseren Tests ist es nicht gelungen, eine mittels GET aus dem Web heruntergeladene Binärdatei in ein von SharePoint akzeptiertes Base64-Format zu enkodieren. Als Workaround blieb nur die direkte Einbettung der bereits Base64-enkodierten Binärdatei in den JavaScript-Code. Nicht schön. Textdateien ließen sich dagegen mittels SP.Base64EncodedByteArray problemlos konvertieren.

Hinweis zu Dateigrößen: die Größenbeschränkung für Dateiuploads per CSOM/JSOM liegt bei wenigen MB (1,5 MBca. 3 MB). Bei der Verwendung von REST für den Upload sollen die Grenzen höher liegen (2 GB).

Arbeit mit der Quick Launch Navigation

Die Quick Launch Navigation stellt dem Nutzer auf der linken Seite Navigationelemente zur Verfügung. Es werden nur zwei Hierarchieebenen unterstützt.

Operation   Bemerkungen
Navigationselemente enumerieren (beide Ebenen)    
Navigationselemente anlegen (beide Ebenen)   Nav.-elemente können evtl. nicht mit leerer URL angelegt werden, verschiedene Farmen reagierten hier unterschiedlich
Bestehende Navigationselemente verändern (Titel, URL)   Nav.-elemente können evtl. nicht mit leerer URL angelegt werden, verschiedene Farmen reagierten hier unterschiedlich
Reihenfolge der Navigationselemente festlegen   beim Erstellen eines Navigationselements möglich, keine Umsortierung bestehender Elemente

Arbeit mit Wikis

Operation   Bemerkungen
Neue, leere Wikiseite anlegen   Inhalt setzen im gleichen Atemzug nicht möglich
Inhalt einer Wikiseite auslesen oder setzen    
Webpart einer Wikiseite hinzufügen  

in die versteckte Webpartzone „wpz“ 1)

Webpart nicht bearbeitbar durch den Anwender

Webpart in den Rich Content einer Wikiseite einbetten   Webpart bearbeitbar durch den Anwender, aber auch entfernbar

1) Webparts können zwar der versteckten Webpartzone „wpz“ hinzugefügt werden, ohne in den Rich Content eingebettet zu werden; diese Webparts verschwinden aber, nachdem der Anwender die Wiki-Seite das erste Mal editiert und speichert. Daher müssen alle hinzugefügten Webparts auch in den Rich Content eingebettet werden.

Arbeit mit Webparts

Operation   Bemerkungen
Webparts einer Seite enumerieren    
Neuen Webpart erstellen und einer Webpartzone hinzufügen   Webpartdefinition wird im XML-Format übergeben
Script Editor Webpart mit gesetztem Script-Inhalt anlegen    
List Form Webpart anlegen    
XsltListViewWebpart anlegen   View des Webparts beim Erstellen setzen ist nicht möglich; es wird ein Default-View erzeugt
Webpart-Eigenschaften eines existierenden Webparts anpassen  

Eventuell können nicht alle Eigenschaften bearbeitet werden 1)

View eines existierenden XsltListViewWebparts anpassen   Es scheint nicht möglich zu sein, den in der Webpart-Definition enthaltenen View anzupassen. 2)
Webpart-Eigenschaften eines existierenden List Form Webparts anpassen   Fehler beim Anpassen eines List Form Webparts 3)

1) Je nach Webpart-Typ sollte geprüft werden, ob alle Eigenschaften über die JSOM-Wrapper-Objekte zur Verfügung gestellt werden. Bspw. ist noch unklar, welche Eigenschaft die Anzeige des Listensuchfelds des XsltListViewWebparts steuert.

2) Ein Workaround wird wahrscheinlich Thema eines eigenen Blog-Beitrags werden.

3) Der Upload der aktualisierten Webpart-Definition eines List Form Webparts schlug auf unseren Systemen fehl. Im ULS-Log gab es Hinweise auf einen Fehler bei der Konvertierung von Daten in das JSON-Format. Es fühlt sich an wie ein SharePoint-Bug.

Arbeit mit Zugriffsberechtigungen

Beachten Sie, dass eine App Full Control-Rechte benötigt, um Zugriffsberechtigungen zu manipulieren. Damit ist die App im Office Store nicht mehr zugelassen.

Operation   Bemerkungen
Berechtigungsgruppe (Permission Level) erstellen    
Listenberechtigungen setzen    
Item-level-Berechtigungen setzen    
Berechtigungsvererbung aufheben    
Berechtigungsvererbung wiederherstellen    

Arbeit mit Social Features

Operation   Bemerkungen
Wer folgt mir?    
Wem folge ich?    
Einer Person folgen    
Einer Person nicht mehr folgen    
User Profile Properties des eigenen Profils auslesen    
User Profile Properties fremder Profile auslesen    

Fazit

JSOM erfordert etwas Umgewöhnung von synchroner auf asynchrone Programmierung. Der C#-Entwickler wünscht sich sofort das async/await-Modell herbei.

Durch die asynchrone Programmierung explodiert der Code-Umfang schnell, wo sonst nur wenige Zeilen Code nötig waren. Der Code ist nicht mehr linear lesbar, daher sollte auf Modularisierung und sprechende Funktionsnamen geachtet werden. Ab und zu ein Kommentar, der den Gesamtzusammenhang erklärt, kann auch nicht schaden.

In der Praxis gab es leider unangenehme Überraschungen beim Einsatz einiger JSOM API-Funktionen. Diese sind in den Übersichten oben gelb und rot hervorgehoben. Es waren alle Probleme lösbar, haben aber für unnötige Mehrarbeit gesorgt.

Im nächsten Projekt hilft die Übersicht in diesem Beitrag hoffentlich, das Überraschungspotential zu verringern.

Ich wünsche allen Lesern einen erfolgreichen und bugfreien Start ins neue Jahr!

Kommentar hinterlassen


Pin It on Pinterest