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öch­ten eine SharePoint-hosted App ent­wi­ckeln, sind sich aber nach der Lektüre mei­nes letz­ten Beitrags nicht sicher, ob sich mit­tels JavaScript Object Model (JSOM) alle Anforderungen abbil­den las­sen (Stichwort: "JSOM-Limitierungen")?

Wir haben den Sprung gewagt und SharePoint-hosted Apps als Vorlage ein­ge­setzt. Dabei haben wir die Möglichkeiten und Grenzen von JSOM ken­nen­ge­lernt.

Dieser Beitrag zeigt, wel­che JSOM-Operationen pro­duk­tiv erfolg­reich ein­ge­setzt wur­den und wo es Probleme gab.

JSOM als Unbekannte

Eigentlich ganz ein­fach: JSOM ist ver­gleich­bar mit CSOM und stellt ein Subset der SharePoint Server-API (SSOM) cli­ent­sei­tig zur Verfügung.

Nur in JavaScript. Und asyn­chron. Und weni­ger doku­men­tiert.

Also doch nicht ein­fach. Die genann­ten Punkte rei­chen bereits, um einen Zeitplan ins Wanken zu brin­gen. Dazu kommt die Unsicherheit, ob sich alle Anforderungen mit JSOM abbil­den las­sen.

Eine Liste häu­fig genutz­ter API-Funktionen ist zwar hilf­reich, doch selbst wenn sie voll­stän­dig wäre, wür­den die Zusammenhänge feh­len. Darüberhinaus bleibt immer der Zweifel, ob in der Praxis funk­tio­niert, was die Dokumentation ver­spricht.

Was fehlt, ist eine Zusammenstellung von JSOM-Operationen, die tat­säch­lich in der Praxis getes­tet wur­den.

Liste getesteter JSOM-Operationen

Den Zweifel, wel­che Anforderungen sich mit­tels JSOM abbil­den las­sen, möchte ich hel­fen aus­zu­räu­men.

Es folgt eine Zusammenstellung der Operationen, die in der Praxis getes­tet wur­den sowie Hinweise auf mög­li­che Probleme. Problematische Operationen sind gelb oder rot gekenn­zeich­net und mit ent­spre­chen­den Bemerkungen ver­se­hen.

Arbeit mit Listen

Operation   Bemerkungen
Listen enu­me­rie­ren   Beispiel
Liste erstel­len  

Beispiel

ein­zelne Spalten kön­nen direkt per XML-Definition über­ge­ben wer­den

Liste ver­än­dern   Beispiel
Liste löschen   Beispiel 
Listenelemente enu­me­rie­ren   Beispiel
Listenelement anle­gen   Beispiel
Listenelement ver­än­dern   Beispiel 
Listenelement löschen   Beispiel

Arbeit mit Listen-Ansichten (Views)

Operation   Bemerkungen
Views enu­me­rie­ren   Beispiel
View erstel­len    
Bestehenden View ver­än­dern  

Beispiel

View-Query-Definition wird als XML über­ge­ben; View-Spalten kön­nen ein­zeln ange­ge­ben wer­den

View als Standardview fest­le­gen    

Arbeit mit Dokumentenbibliotheken

Operation   Bemerkungen
DocLibs enu­me­rie­ren    
DocLib erstel­len    
DocLib ver­än­dern    
DocLib löschen    
(Unter-)Ordner anle­gen    
Text-Datei hoch­la­den (Root- oder Unterverzeichnis)   muss Base64-enko­diert wer­den
Binär-Datei hoch­la­den (Root- oder Unterverzeichnis)   muss Base64-enko­diert wer­den 1)

1) Dateien müs­sen Base64-enkodiert in eine Dokumentenbibliothek hoch­ge­la­den wer­den, was auch ohne Probleme funk­tio­niert. Problematisch kann es sein, Binärdaten nach Base64 zu enko­die­ren, da die Handhabung von Binärdaten in älte­ren Browsern wie dem IE8 nicht gut unter­stützt wird – hier feh­len oft die benö­tig­ten Datenstrukturen. In unse­ren Tests ist es nicht gelun­gen, eine mit­tels GET aus dem Web her­un­ter­ge­la­dene Binärdatei in ein von SharePoint akzep­tier­tes Base64-Format zu enko­die­ren. Als Workaround blieb nur die direkte Einbettung der bereits Base64-enkodierten Binärdatei in den JavaScript-Code. Nicht schön. Textdateien lie­ßen sich dage­gen mit­tels SP.Base64EncodedByteArray pro­blem­los kon­ver­tie­ren.

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

Arbeit mit der Quick Launch Navigation

Die Quick Launch Navigation stellt dem Nutzer auf der lin­ken Seite Navigationelemente zur Verfügung. Es wer­den nur zwei Hierarchieebenen unter­stützt.

Operation   Bemerkungen
Navigationselemente enu­me­rie­ren (beide Ebenen)    
Navigationselemente anle­gen (beide Ebenen)   Nav.-elemente kön­nen evtl. nicht mit lee­rer URL ange­legt wer­den, ver­schie­dene Farmen reagier­ten hier unter­schied­lich
Bestehende Navigationselemente ver­än­dern (Titel, URL)   Nav.-elemente kön­nen evtl. nicht mit lee­rer URL ange­legt wer­den, ver­schie­dene Farmen reagier­ten hier unter­schied­lich
Reihenfolge der Navigationselemente fest­le­gen   beim Erstellen eines Navigationselements mög­lich, keine Umsortierung bestehen­der Elemente

Arbeit mit Wikis

Operation   Bemerkungen
Neue, leere Wikiseite anle­gen   Inhalt set­zen im glei­chen Atemzug nicht mög­lich
Inhalt einer Wikiseite aus­le­sen oder set­zen    
Webpart einer Wikiseite hin­zu­fü­gen  

in die ver­steckte Webpartzone "wpz" 1)

Webpart nicht bear­beit­bar durch den Anwender

Webpart in den Rich Content einer Wikiseite ein­bet­ten   Webpart bear­beit­bar durch den Anwender, aber auch ent­fern­bar

1) Webparts kön­nen zwar der ver­steck­ten Webpartzone "wpz" hin­zu­ge­fügt wer­den, ohne in den Rich Content ein­ge­bet­tet zu wer­den; diese Webparts ver­schwin­den aber, nach­dem der Anwender die Wiki-Seite das erste Mal edi­tiert und spei­chert. Daher müs­sen alle hin­zu­ge­füg­ten Webparts auch in den Rich Content ein­ge­bet­tet wer­den.

Arbeit mit Webparts

Operation   Bemerkungen
Webparts einer Seite enu­me­rie­ren    
Neuen Webpart erstel­len und einer Webpartzone hin­zu­fü­gen   Webpartdefinition wird im XML-Format über­ge­ben
Script Editor Webpart mit gesetz­tem Script-Inhalt anle­gen    
List Form Webpart anle­gen    
XsltListViewWebpart anle­gen   View des Webparts beim Erstellen set­zen ist nicht mög­lich; es wird ein Default-View erzeugt
Webpart-Eigenschaften eines exis­tie­ren­den Webparts anpas­sen  

Eventuell kön­nen nicht alle Eigenschaften bear­bei­tet wer­den 1)

View eines exis­tie­ren­den XsltListViewWebparts anpas­sen   Es scheint nicht mög­lich zu sein, den in der Webpart-Definition ent­hal­te­nen View anzu­pas­sen. 2)
Webpart-Eigenschaften eines exis­tie­ren­den List Form Webparts anpas­sen   Fehler beim Anpassen eines List Form Webparts 3)

1) Je nach Webpart-Typ sollte geprüft wer­den, ob alle Eigenschaften über die JSOM-Wrapper-Objekte zur Verfügung gestellt wer­den. Bspw. ist noch unklar, wel­che Eigenschaft die Anzeige des Listensuchfelds des XsltListViewWebparts steu­ert.

2) Ein Workaround wird wahr­schein­lich Thema eines eige­nen Blog-Beitrags wer­den.

3) Der Upload der aktua­li­sier­ten Webpart-Definition eines List Form Webparts schlug auf unse­ren 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 mani­pu­lie­ren. Damit ist die App im Office Store nicht mehr zuge­las­sen.

Operation   Bemerkungen
Berechtigungsgruppe (Permission Level) erstel­len    
Listenberechtigungen set­zen    
Item-level-Berechtigungen set­zen    
Berechtigungsvererbung auf­he­ben    
Berechtigungsvererbung wie­der­her­stel­len    

Arbeit mit Social Features

Operation   Bemerkungen
Wer folgt mir?    
Wem folge ich?    
Einer Person fol­gen    
Einer Person nicht mehr fol­gen    
User Profile Properties des eige­nen Profils aus­le­sen    
User Profile Properties frem­der Profile aus­le­sen    

Fazit

JSOM erfor­dert etwas Umgewöhnung von syn­chro­ner auf asyn­chrone Programmierung. Der C#-Entwickler wünscht sich sofort das async/await-Modell her­bei.

Durch die asyn­chrone Programmierung explo­diert der Code-Umfang schnell, wo sonst nur wenige Zeilen Code nötig waren. Der Code ist nicht mehr linear les­bar, daher sollte auf Modularisierung und spre­chende Funktionsnamen geach­tet wer­den. Ab und zu ein Kommentar, der den Gesamtzusammenhang erklärt, kann auch nicht scha­den.

In der Praxis gab es lei­der unan­ge­nehme Überraschungen beim Einsatz eini­ger JSOM API-Funktionen. Diese sind in den Übersichten oben gelb und rot her­vor­ge­ho­ben. Es waren alle Probleme lös­bar, haben aber für unnö­tige Mehrarbeit gesorgt.

Im nächs­ten Projekt hilft die Übersicht in die­sem Beitrag hof­fent­lich, das Überraschungspotential zu ver­rin­gern.

Ich wün­sche allen Lesern einen erfolg­rei­chen und bug­freien Start ins neue Jahr!

Related Posts

Pin It on Pinterest