Table of Contents

pitFM Add-on - Microsoft SharePoint via MS-Graph-API (pitFM_MsSharePointViaGraph.dll)

Dieses Add-on kapselt ausgewählte SharePoint-Funktionalitäten und stellt diese über die Microsoft Graph API zur Verfügung.
Der Zugriff erfolgt abstrahiert, sodass keine direkte Interaktion mit der Graph API erforderlich ist.

Unterstützte Funktionen sind:

  • Auflisten der Kindelemente eines angegebenen SharePoint-Ordners
  • Auflisten aller Kindelemente einer angegebenen SharePoint-Dokumentbibliothek
    • Einschränkung auf die Kindelemente, welche seit dem angegebenen Zeitpunkt verändert wurden
  • Herunterladen von Dateien
    • über die SharePoint-URL
    • über die DriveItem-ID
  • Hochladen von Dateien in ein SharePoint-Verzeichnis unter Angabe eines lokalen Dateipfads
  • Löschen eines DriveItems im SharePoint
    • basierend auf der DriveItem-ID
  • Ermitteln der DriveItem-ID anhand der absoluten Url im SharePoint
    • basierend auf SharePoint-URL inkl. Dateipfad
  • Ermitteln des vollständigen Pfads eines DriveItems im SharePoint
    • basierend auf der DriveItem-ID
  • Alle Felder des DriveItems und ListItems als JSON liefern
    • basierend auf der DriveItem-ID

Allgemeines zu MS Sharepoint und dem Add-on

Im Add-on werden die Begriffe Drive und Dokumentbibliothek gleichbedeutend verwendet. Ebenso werden Ordner (deutsch) und Folder (englisch) synonym verwendet.

Ein Drive ist eine Sammlung von Dokumenten und Ordnern und stellt das Hauptverzeichnis (Root) dar. Dokumente und Ordner werden gemeinsam als DriveItems bezeichnet.

Jedes Dokument und jeder Ordner besitzt eine eindeutige ID, die nur innerhalb eines Drives eindeutig ist. Über diese ID können Dokumente auf dem SharePoint-Server referenziert werden, ohne den vollständigen Pfad anzugeben.

Die Verwendung von IDs ist wichtig, da sich Pfade durch Umbenennen oder Verschieben von Dokumenten ändern können, die ID jedoch stabil bleibt. Solange ein DriveItem existiert, ändert sich seine ID nicht.

Beim Hochladen oder Einchecken eines Dokuments gibt das Add-on immer die ID des Dokuments zurück, damit der Zugriff auf das Dokument auch bei späteren Umbenennungen oder Verschiebungen erhalten bleibt.

Das Add-on unterstützt URL-kodierte SharePoint-URLs als auch Leerzeichen im Namen von Microsoft-Graph-Pfaden. Bsp.:

// URL-kodierte SharePoint-URL
https://pitcup.sharepoint.com/sites/TestSite/Shared%20Documents/Budget%20November/Test.docx

// Leerzeichen im Namen von Microsoft-Graph-Pfaden
https://pitcup.sharepoint.com/sites/TestSite/Shared Documents/Budget November/Test.docx

Technisches

Code-Repository: https://dev.azure.com/pit-cup/pitFM_Addons/_git/pitFM_MsSharePointViaGraph

Releaseverzeichnis:
X:\FM\AddOns\MsSharePointViaGraph
pitftp.de/pitFM_AddOns/MsSharePointViaGraph

Dieses Add-on wird vorerst als Merged-DLL geliefert, da pit erst ab Version 27 die Unterverzeichnisse für Add-ons unterstützt. Im AppConfig-Branch wird der Stand gehalten, mit welchem keine Merged-DLL erstellt wird. Dafür wird die AppConfig mit den Binding-Redirects erzeugt, welche in die pitfm.exe.config übernommen werden können.

Info zum Common-Namespace

Die Klassen im Common-Namespace wurden in das Nuget-Paket pit.pitFm.Common ausgelagert. Klassen, welche jetzt noch im Common-Namespace liegen, überschreiben oder erweitern die Funktionalität aus pit.pitFm.Common.

Logging (teilweise veraltet)

Ebene Aufgabe Welche Logs? Log-Level
Adapter Direkte Kommunikation mit der API - Request-Daten (ohne sensible Infos)
- Response-Statuscodes
- Fehler (Timeouts, Bad Requests, Server Errors)		 Info (Erfolgreiche Requests)
Warning (Fehlerhafte Antworten)
Error (Timeouts, unerwartete Fehler)
Service Geschäftslogik und Fehlerhandling - Wichtige Aktionen in der App
- Ob API-Call erfolgreich war oder eine andere Strategie nötig ist
- Kontext der API-Nutzung (Warum wird der Call gemacht?)		 Info (Erfolgreiche Verarbeitung)
Warning (Fehlversuche mit Fallback-Strategie)
Error (Wenn API-Fehler die Funktionalität beeinträchtigen)

Berechtigung für das Add-on

Es wird empfohlen, mit Client Secret zu arbeiten.
Die Vergabe und Pflege von Benutzerberechtigungen in SharePoint erfordert detailliertes Administrationswissen und ist fehleranfällig. Durch die Verwendung eines Client Secrets erfolgt der Zugriff im App-Kontext und ist unabhängig von einzelnen Benutzerkonten.

Die Berechtigungen einer Microsoft-Graph-App-Registrierung können auf unterschiedlichen Wegen definiert und genehmigt werden.
Voraussetzung ist eine bestehende App-Registrierung, die unter
portal.azure.com → Microsoft Entra ID → Verwalten → App-Registrierungen → „Neue Registrierung“
erstellt werden kann.

Delegated Permissions / Delegierte Berechtigungen (Admin-Zustimmung)

In der App-Registrierung können delegierte Berechtigungen definiert und hinzugefügt werden.
Dies erfolgt unter
App-Registrierung auswählen → Verwalten → API-Berechtigungen.

Das bloße Hinzufügen der Berechtigungen reicht für die Authentifizierung nicht aus.
Ein Azure-Administrator kann jedoch für diese Berechtigungen eine Admin-Zustimmung erteilen. Dadurch entfällt die individuelle Zustimmung der Nutzer beim Anmelden.

Die vom Add-on verwendeten Berechtigungen sind im weiteren Verlauf dieser Dokumentation aufgeführt.
Zusätzlich müssen die entsprechenden Berechtigungen im SharePoint Admin Center freigegeben werden.

Application Permissions / Anwendungsberechtigungen (Admin-Zustimmung)

Wird das Add-on im App-Kontext betrieben und authentifiziert sich über ein Client Secret
(MsSharePointViaGraph_InitializeByClientSecret()),
müssen die erforderlichen Berechtigungen als Anwendungsberechtigungen konfiguriert und vom Azure-Administrator genehmigt werden.

Diese Berechtigungen gelten tenantweit und sind nicht an einen Benutzerkontext gebunden.

Delegated Permissions/Delegierte Berechtigungen durch den Nutzer erteilen

Wenn der Azure Admin die delegierten Berechtigungen nicht erteilt hat, muss jeder Nutzer einmalig die Berechtigungen erteilen. Mit dem interaktiven Login wird der Nutzer direkt beim ersten Login gefragt, ob er die Berechtigungen erteilt. Wenn der Nutzer nicht zustimmt, kann das Add-on nicht auf die Graph-API zugreifen. Der Nutzer wird beim nächsten Login erneut nach der Zustimmung gefragt.

Beim nicht interaktiven Login muss der Nutzer vor dem Login des Add-ons die Berechtigungen erteilen. Also bevor MsSharePointViaGraph_InitializeByUserLogin() ausgeführt wird. Folgende URL muss erzeugt und im Browser ausgeführt werden. Es ist die {TENANT_ID} und die {CLIENT_ID} inklusive der geschweiften {} zu ersetzen. Das letzte Argument, der Scope ist die Berechtigung. Hier in dem Beispiel "User.Read".
Nach dem Aufruf der URL im Browser muss man sich mit den Logindaten einloggen, welche auch im MsSharePointViaGraph Add-on verwendet werden sollen. Nach dem Login wird ein Bestätigungsdialog angezeigt, in welchem man alle angefragten Berechtigungen aufgelistet bekommt. Die Berechtigungen müssen bestätigt werden. Danach funktioniert das Add-on mit diesen Logindaten.

https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize?client_id={CLIENT_ID}&response_type=code&scope=User.Read

Wenn die Methode MsSharePointViaGraph_InitializeByUserLogin verwendet wird, müssen folgende Berechtigungen erteilt werden. Am besten die folgende URL nutzen und Tenant, sowie ClientId anpassen.
ACHTUNG: Wenn eine Berechtigung nicht gegeben wurde, funktioniert das GraphClient Add-on nicht. Bis auf die Shared-Berechtigungen müssen alle, in der Liste aufgeführten, Berechtigungen gegeben werden.

# Delegierte Berechtigungen erteilen 
https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize?client_id={CLIENT_ID}&response_type=code&scope=User.Read%20Mail.ReadWrite%20Mail.Send%20Calendars.ReadWrite%20Contacts.ReadWrite

# Delegierte Berechtigungen für die Nutzung von Schared-Mailboxen erteilen
https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize?client_id={CLIENT_ID}&response_type=code&scope=User.Read%20Mail.ReadWrite.Shared%20Mail.Send.Shared

# Mehrere Berechtigungen übergeben durch Separator %20 
&scope=User.Read%20Mail.ReadWrite%20Mail.Send

Sonderfall Interaktiver Login

Mit dem interaktiven User-Login authentifiziert sich der Nutzer über einen Popup-Dialog bei seinem MS-Graph Dienst. In dem Login-Dialog wird nach erfolgreicher Authentifizierung die Zustimmung für die benötigten Berechtigungen abgefragt. Diese müssen bestätigt werden. Nach der Bestätigung ist die Authentifizierung abgeschlossen und der MS Graph Client erhält den Accesstoken und den Refreshtoken. Die Tokens werden in einem Cache unter folgendem Pfad abgelegt. %LocalAppData%\pitcup\pitFM\addons\pitFM_MsSharePointViaGraph Die interaktive Authentifizierung kann nicht in einem pitIS oder als Service verwendet werden.

Aktuell benötigte Berechtigungen

Berechtigung Login-Mechanismus Weitere Informationen
Files.ReadWrite.All Delegiert / via User-Login
Sites.ReadWrite.All Delegiert / via User-Login
- -
Files.ReadWrite.All Anwendung / via Client-Secret
Sites.ReadWrite.All Anwendung / via Client-Secret

Release Notes

Version 0.0.1

  • Neue Funktionen
    • Kindelemente des angegebenen Folders anzeigen
    • Datei runterladen - anhand der SharePoint-URL
    • Datei runterladen - anhand der DriveItem-ID
    • Datei hochladen - mit Angabe des Dateipfades
    • Existiert Datei im SharePoint - SharePoint-URL inkl. Dateipfad

Version 0.0.2 (auf Anfrage)

  • Unterstützung der DokumentBibliothek "Shared Documents"
  • ListChildrenOfFolder liefert die Daten mit Doppelpunkt als Trennzeichen.
  • Die Funktion zum Prüfen, ob eine Datei existiert wurde ersetzt durch das Ermitteln der DriveItem-ID zu einer Url.
  • Neue Funktionen
    • DriveItem im SharePoint löschen - anhand der DriveItem-ID
    • Alle Felder eines DriveItems als JSON liefern - anhand der DriveItem-ID
    • DriveItem-ID im SharePoint ermitteln - anhand der SharePoint-URL inkl. Dateipfad
    • Pfad eines DriveItems im SharePoint ermitteln - anhand der DriveItem-ID
    • Auflisten aller Kindelemente einer angegebenen SharePoint-Dokumentbibliothek
      • Einschränkung auf die Kindelemente, welche seit dem angegebenen Zeitpunkt verändert wurden
  • Entfernte Funktionen
    • Existiert Datei im SharePoint - SharePoint-URL inkl. Dateipfad

Zukünftige Features

  • Attributwerte lesen und schreiben
  • Dokument (Word, Excel, PowerPoint) als PDF herunterladen
  • Url zu Dokument abfragen, um diese Url im Browser öffnen zu können. -> Das Feld webUrl enthält diesen Link.
    • ist bereits über die Abfrage des JSON eines DriveItems verfügbar
  • Vorerst verworfen:
    • Ordner erstellen, umbenennen, löschen
      • Funktionalität soll über die Weboberfläche von SharePoint verwendet werden.
      • Der Ordner wird beim Upload eines Dokuments automatisch erstellt, wenn er nicht existiert.
    • Selektives Abfragen von Eigenschaften eines Dokuments z.B. createdBy, lastModifiedDateTime, lastModifiedBy
      • Vorerst werden alle Felder eines DriveItems als Json geliefert

Für Entwickler

Die Dokumentation zur MS Graph REST API v1.0 ist unter https://learn.microsoft.com/de-de/graph/api/overview?view=graph-rest-1.0&preserve-view=true abrufbar.

Microsoft stellt mit dem Graph Explorer unter https://developer.microsoft.com/en-us/graph/graph-explorer
ein webbasiertes Tool zur Verfügung, um API-Requests direkt auszuführen und zu testen; ohne eigene Client-Implementierung.

Mit dem Graph Explorer können:

  • API-Requests interaktiv abgesetzt und modifiziert werden
  • benötigte Delegated Permissions und Application Permissions eingesehen und (nach Anmeldung) freigegeben werden
  • HTTP-Responses, Statuscodes und Response-Payloads direkt analysiert werden
  • unterschiedliche Benutzer-Kontexte simuliert werden (abhängig von den erteilten Rechten)

Der Graph Explorer eignet sich damit sowohl für erste Explorationen der API als auch für Debugging, Berechtigungsanalysen und die Vorbereitung einer späteren Integration in eigene Anwendungen oder Automatisierungen.

Migration von SharePoint-Online (CSOM) zu MS Graph

Laut Microsoft Dokumentation kann man auf ein ListItem welches man aus CSOM mittels UniqueId referenziert, in MS Graph wie die DriveItem-ID referenzieren.
https://learn.microsoft.com/en-us/graph/api/driveitem-get?view=graph-rest-1.0&tabs=http
Dadurch sollte der Aufruf der Methoden, welche die DriveItem-ID als Parameter erwarten, auch mit UniqueId funktionieren.

Alternativ kann ein Dokument mit seiner Absoluten URL runtergeladen werden. Auch das Abfragen deren Felder und die DriveItem-ID ist möglich.

Exception-Handling des Add-ons

Das Add-on besitzt ein geschlossenes Exception-Handling.
Alle innerhalb des Add-ons auftretenden Exceptions werden intern abgefangen und nicht an den Aufrufer weitergereicht.
Add-on-Methoden werfen grundsätzlich keine Exceptions.

Für aufrufenden Code ist daher kein try/catch um Add-on-Methoden notwendig oder vorgesehen.

Tritt während eines Methodenaufrufs ein Fehler auf, wird:

  • eine kompakte, für den Aufrufer bestimmte Fehlermeldung über
    MsSharePointViaGraph_GetLastError() bereitgestellt
  • die vollständige Exception inkl. Stacktrace in den Trace des pitFM-Prozesses geschrieben
    (einsehbar z. B. mit DebugView oder vergleichbaren Trace-Tools)

Klassifizierung von Fehlern

  • Vorgesehene (erwartete) Fehlerfälle werden mit klaren, fachlich verständlichen Fehlermeldungen über
    MsSharePointViaGraph_GetLastError() signalisiert.
  • Nicht vorgesehene (unerwartete) Exceptions werden ebenfalls intern abgefangen und in
    MsSharePointViaGraph_GetLastError() mit dem Präfix
    unexpected exception=
    gekennzeichnet.

Funktionen

Kurzübersicht der Add-on-Funktionen

Nachfolgend werden alle verfügbaren MsGraph Funktionalitäten aufgelistet.
Nach dieser Tabelle werden die Funktionen detailliert beschrieben.

Funktionalität Funktionsname
Kindelemente des angegebenen Folders anzeigen ListChildrenOfFolder
Alle Kindelemente einer SharePoint-Dokumentbibliothek anzeigen ListChildrenOfLibrary
Datei runterladen - anhand der SharePoint-URL DownloadFile
Datei runterladen - anhand der DriveItem-ID DownloadFileById
Datei hochladen - mit Angabe des Dateipfades UploadFile
DriveItem im SharePoint löschen - anhand der DriveItem-ID DeleteDriveItemById
DriveItem-ID im SharePoint ermitteln - anhand der SharePoint-URL inkl. Dateipfad GetDriveItemIdForAbsoluteUrl
Url eines DriveItems im SharePoint ermitteln - anhand der DriveItem-ID GetRelativeUrlForDriveItemId
Alle Felder eines Drive-/ListItems als JSON liefern - anhand der DriveItem-ID GetJsonOfDriveItem

Logging de-/aktivieren

Das Logging wird mit dem Setzen eines gültigen Log-Levels aktiviert. Dann werden alle Meldungen in den Windows-Trace geschrieben. Diese Meldungen können mit einem TraceListener gelesen werden. Windows stellt mit DebugView ein Tool zur Verfügung, welches die Traces anzeigen und speichern kann. Gültige Log-Level sind der Summary unten zu entnehmen.

/// <summary>
/// Legt das globale Log-Level fest.
/// Wird das Log-Level auf einen ungültigen Wert gesetzt, wird das Logging deaktiviert.
/// </summary>
/// <param name="level">Das Log-Level: Trace=0, Debug=1, Info=2, Warning=3, Error=4, Fatal=5.</param>
public static void MsSharePointViaGraph_SetLogLevel(int level)

Fehlerbehandlung

Wenn bei einer Funktion ein Fehler auftritt, wird dieser mit dem ReturnCode false angezeigt. Der Fehler kann danach mit folgenden Befehlen abgefragt werden.

/// <summary>
/// Gibt an, ob ein LastError vorhanden ist.
/// </summary>
/// <returns>
/// True, wenn ein LastError vorliegt; ansonsten false.
/// </returns>
public static bool MsSharePointViaGraph_HasLastError()

/// <summary>
/// Liefert den letzten aufgetretenen Fehler zurück.
/// </summary>
/// <returns>Fehlermeldung als Text.</returns>
public static string MsSharePointViaGraph_GetLastError()

Es kann auch eine Fehlerhistorie abgefragt werden. Diese enthält alle Fehler, die seit der Initialisierung mit MsSharePointViaGraph_InitializeByClientSecret und MsSharePointViaGraph_InitializeByUserLogin aufgetreten sind.

/// <summary>
/// Liefert alle aufgetretenen Fehler seit der Initialisierung zurück.
/// </summary>
/// <returns>Die Fehlermeldungen sind zeilenweise enthalten. Trenner ist "\r\n".</returns>
public static string MsSharePointViaGraph_GetErrorHistory()

Proxy-Server angeben

Der Proxy-Server muss vor der Initialisierung des Add-ons angegeben werden.

/// <summary>
/// Erstellt die Proxykonfiguration.
/// <remarks>
/// Diese Funktion muss vor den Initialize-Funktionen <see cref="PitFmInterface.MsSharePointViaGraph_InitializeByClientSecret"/> bzw. <see cref="PitFmInterface.MsSharePointViaGraph_InitializeByUserLogin"/> aufgerufen werden.
/// Alternativ muss nach dem Aufruf dieser Methode die Initialisierung mit den Authentifizierungs-Informationen erneut durchgeführt werden.
/// </remarks>
/// </summary>
/// <param name="proxyAddress">Die Adresse des Proxyservers.</param>
/// <param name="username">Optional: Der UserName zur Authentifizierung am Proxy.</param>
/// <param name="password">Optional: Das Passwort zur Authentifizierung am Proxy.</param>
/// <param name="domain">Optional: Die Domäne, die diesen Anmeldeinformationen zugeordnet ist.</param>
public static void MsSharePointViaGraph_DefineWebProxy(string proxyAddress, string username = null, string password = null, string domain = null)

Add-on initialisieren

Das Add-on muss vor der Nutzung mit den notwendigen Daten initialisiert werden.

/// <summary>
/// Initialisiert den GraphClient mittels ClientSecret.
/// </summary>
/// <param name="tenantId">Die Tenant-/Mandant-/Verzeichnis-ID.</param>
/// <param name="clientId">Die Client-/Anwendungs-/App-ID.</param>
/// <param name="clientSecret">Das Client-Secret.</param>
/// <param name="requestTimeoutInSeconds">Timeout für alle Requests in Sekunden. standard = 120s.</param>
public static void MsSharePointViaGraph_InitializeByClientSecret(
    string tenantId,
    string clientId,
    string clientSecret,
    int requestTimeoutInSeconds = 0)

/// <summary>
/// Diese Methode ist veraltet, da sie keine Multi-Faktor-Authentifizierung (MFA) unterstützt.
/// Initialisiert den GraphClient mittels Nutzername und Passwort.
/// </summary>
/// <param name="tenantId">Die Tenant-/Mandant-/Verzeichnis-ID.</param>
/// <param name="clientId">Die Client-/Anwendungs-/App-ID.</param>
/// <param name="user">Der Nutzername bzw. die E-Mail-Adresse des Nutzers.</param>
/// <param name="password">Das Passwort zu dem Nutzeraccount.</param>
/// <param name="requestTimeoutInSeconds">Timeout für alle Requests in Sekunden. standard = 120s.</param>
/// <remarks>Diese Methode verwendet von MS Graph als obsolet markierte Methoden. MFA - Multi-Faktor-Authentifizierung wird nicht unterstützt.</remarks>
public static void MsSharePointViaGraph_InitializeByUserLogin(
    string tenantId,
    string clientId,
    string user,
    string password,
    int requestTimeoutInSeconds = 0)
    
/// <summary>
/// Initialisiert den GraphClient mittels interaktiver Authentifizierung.
/// </summary>
/// <param name="tenantId">Die Tenant-/Mandant-/Verzeichnis-ID.</param>
/// <param name="clientId">Die Client-/Anwendungs-/App-ID.</param>
/// <param name="requestTimeoutInSeconds">Timeout für alle Requests in Sekunden. standard = 120s.</param>
public static void MsSharePointViaGraph_InitializeByInteractiveUserLogin(
    string tenantId,
    string clientId,
    int requestTimeoutInSeconds = 0)
            
/// <summary>
/// Löscht den aktuellen Token-Cache aus dem interaktiven Login.
/// Kann notwendig sein, wenn sich ein anderer Nutzer authentifizieren soll.
/// </summary>
public static void MsSharePointViaGraph_DeleteUserToken()

Dokumentübersicht

/// <summary>
/// Listet alle Dokumente und Verzeichnisse aus der übergebenen SharePoint-URL auf.
/// <remarks>
/// Die URL muss vollständig sein und mindestens die Site sowie DokumentBibliothek enthalten
/// z.B. https://contoso.sharepoint.com/sites/mySite/Shared%20Documents/Wichtiges/2025_November
/// Es wird ein Array geliefert, welches pro Eintrag die DriveItem-ID und die relative URL zum Dokument enthält.
/// Die DriveItem-ID und die URL sind durch Doppelpunkt getrennt.
/// </remarks>
/// <example>
/// Response:
/// ["01W5QB2ZLXJBMPCY3LXFAIZCVV247QCMYQ:/sites/Addons/DocumentLibraryPMA/main-pma",
/// "01W5QB2ZKPYBYMSZ2I6JC3PGA3YUPTH4LI:/sites/Addons/DocumentLibraryPMA/Calculation-pma.xlsx"]
/// </example>
/// </summary>
/// <param name="absoluteFolderUrl">SharePoint-URL inklusive Site, DokumentBibliothek und ggf. Ordnerpfad.</param>
/// <returns>Liefert das Array mit den Child-Elementen. Im Fehlerfall wird null zurückgegeben.</returns>
public static string[] MsSharePointViaGraph_ListChildrenOfFolder(string absoluteFolderUrl)

/// <summary>
/// Listet alle Dokumente und Verzeichnisse aus der übergebenen SharePoint-URL auf.
/// <remarks>
/// Die URL muss vollständig sein und mindestens die Site sowie DokumentBibliothek enthalten
/// z.B. https://contoso.sharepoint.com/sites/mySite/Shared%20Documents/Wichtiges/2025_November
/// Es wird ein Array geliefert, welches pro Eintrag die DriveItem-ID und die relative URL zum Dokument enthält.
/// Die DriveItem-ID und die URL sind durch Doppelpunkt getrennt.
/// </remarks>
/// <example>
/// Response:
/// ["01W5QB2ZLXJBMPCY3LXFAIZCVV247QCMYQ:/sites/Addons/DocumentLibraryPMA/main-pma",
/// "01W5QB2ZKPYBYMSZ2I6JC3PGA3YUPTH4LI:/sites/Addons/DocumentLibraryPMA/Calculation-pma.xlsx"]
/// </example>
/// </summary>
/// <param name="absoluteFolderUrl">SharePoint-URL inklusive Site, DokumentBibliothek und ggf. Ordnerpfad.</param>
/// <param name="minModificationDateTime">
/// Optional: Liefert nur die Kindelemente, welche seit der angegebenen Modification-DateTime verändert wurden.
/// Wenn null gesetzt ist, werden alle DriveItems der Dokumentbibliothek geliefert.
/// Achtung: Kann eine hohe Last im SharePoint erzeugen, wenn die Dokumentbibliothek sehr viele Dokumente und Ordner enthält.
/// </param>
/// <returns>Liefert das Array mit den Child-Elementen. Im Fehlerfall wird null zurückgegeben.</returns>
public static string[] MsSharePointViaGraph_ListChildrenOfLibrary(string absoluteSharePointFolderUrl, DateTime minModificationDateTime = default)

/// <summary>
/// Ermittelt die DriveItem-ID zu einer absoluten SharePoint-URL.
/// </summary>
/// <remarks>
/// Die angegebene URL muss auf ein gültiges DriveItem (z. B. Datei oder Ordner)
/// innerhalb einer SharePoint-Dokumentbibliothek verweisen.
/// Kann keine DriveItem-ID ermittelt werden, gibt die Methode einen leeren String zurück.
/// In diesem Fall sollte zusätzlich der zuletzt aufgetretene Fehler (LastError)
/// geprüft werden, da z. B. ein Authentifizierungs- oder Berechtigungsfehler vorliegen kann.
/// </remarks>
/// <param name="absoluteDriveItemUrl">
/// Absolute URL eines DriveItems in SharePoint.
/// </param>
/// <returns>
/// DriveItem-ID des referenzierten Elements, wenn es existiert,
/// andernfalls ein leerer String.
/// </returns>
public static int MsSharePointViaGraph_GetDriveItemIdForAbsoluteUrl(string absoluteDriveItemUrl)

/// <summary>
/// Liefert die relative URL zu der übergebenen DriveItem-ID aus einer SharePoint-DokumentBibliothek.
/// Beispiel-Response: "/sites/MySiteName/Shared Documents/MySubFolder/MyFile.txt"
/// </summary>
/// <param name="absoluteLibraryUrl">Absolute URL zur SharePoint-Dokumentbibliothek, in der sich das DriveItem befindet.</param>
/// Diese URL muss die Site sowie den Pfad zur Dokumentbibliothek enthalten.</param>
/// <param name="driveItemId">Eindeutige DriveItem-ID der Datei oder des Ordners.</param>
/// <returns>Liefert die relative URL des gefundenen DriveItems.</returns>
public static string MsSharePointViaGraph_GetRelativeUrlForDriveItemId(string absoluteLibraryUrl, string driveItemId)

Details zu einem DriveItem/ListItem abfragen

Mit der Methode MsSharePointViaGraph_GetJsonOfDriveItem können alle Felder eines DriveItems abgefragt werden. Diese werden als JSON-String geliefert.
Es werden auch alle Felder und Custom-Felder des ListItems geliefert. Die Custom-Felder werden unter listItem/fields angezeigt. Wenn die Custom-Felder null sind, werden sie nicht in dem JSON-String angezeigt. Dieses Verhalten kommt von der Graph-API.

/// <summary>
/// Liefert die vollständige JSON-Repräsentation eines DriveItems aus einer SharePoint-Dokumentbibliothek.
/// </summary>
/// <remarks>
/// Die Rückgabe enthält sowohl die DriveItem-Eigenschaften als auch – sofern vorhanden –
/// die zugehörigen ListItem-Felder (z. B. benutzerdefinierte Spalten).
/// Die Daten entsprechen der Microsoft-Graph-Repräsentation des DriveItems.
/// </remarks>
/// <example>Mit der Methode JsonGetValue können Werte aus dem Json abgefragt werden.
///   <code>
///   $jsonResponse = MsSharePointViaGraph_GetJsonOfDriveItem(...);
///
///   JSON-Response-Beispiel
///   {
///      ...,
///      "lastModifiedBy": {
///         "user": {
///             "email": "max.mustermann@3jzpnz.onmicrosoft.com",
///             "id": "a27a7c70-22c0-4962-8901-5af44cf6d3d9",
///             "displayName": "Max Mustermann"
///         }
///      },
///      ...
///      "listItem": {
///        "fields": { ... },
///      }
///   }
///
///   JsonGetValue($jsonResponse, "lastModifiedBy", $jsonElementLastModifiedBy);
///   JsonGetValue($jsonElementLastModifiedBy, "user", $jsonElementUser);
///   JsonGetValue($jsonElementUser, "displayName", $lastModifiedByUserName);
///   </code>
/// </example>
/// <param name="absoluteLibraryUrl">Absolute URL zur SharePoint-Dokumentbibliothek, in der sich das DriveItem befindet.</param>
/// <param name="driveItemId">Eindeutige DriveItem-ID der Datei oder des Ordners.</param>
/// <returns>JSON-String mit allen verfügbaren Feldern des DriveItems.</returns>
public static string MsSharePointViaGraph_GetJsonOfDriveItem(string absoluteLibraryUrl, string driveItemId);

Dokument Download

/// <summary>
/// Lädt eine Datei über eine absolute SharePoint-URL herunter und speichert sie
/// im angegebenen lokalen Zielverzeichnis.
/// </summary>
/// <remarks>
/// Der Dateiname wird aus der Quell-URL ermittelt.
/// Bei Fehlern oder Ausnahmen wird kein Throw ausgelöst; die Methode gibt in diesem Fall
/// einen leeren String zurück.
/// </remarks>
/// <param name="absoluteSourceFileUrl">
/// Absolute URL der Datei in SharePoint (inklusive vollständigem Dateipfad).
/// </param>
/// <param name="targetPath">
/// Lokales Zielverzeichnis für die heruntergeladene Datei.
/// Der Dateiname darf hier nicht enthalten sein.
/// </param>
/// <returns>
/// Vollständiger lokaler Dateipfad der gespeicherten Datei bei Erfolg,
/// andernfalls ein leerer String.
/// </returns>
public static string MsSharePointViaGraph_DownloadFile(string absoluteSourceFileUrl, string targetPath)

/// <summary>
/// Lädt eine Datei anhand ihrer DriveItem-ID aus einer SharePoint-Dokumentbibliothek
/// herunter und speichert sie im angegebenen lokalen Zielverzeichnis.
/// </summary>
/// <remarks>
/// Die Datei wird über Microsoft Graph anhand der DriveItem-ID ermittelt.
/// Der Dateiname wird aus den Metadaten des DriveItems abgeleitet.
/// Bei Fehlern oder Ausnahmen wird kein Throw ausgelöst; die Methode gibt in diesem Fall
/// einen leeren String zurück.
/// </remarks>
/// <param name="absoluteLibraryUrl">Absolute URL zur SharePoint-Dokumentbibliothek, in der sich das DriveItem befindet.</param>
/// <param name="driveItemId">Eindeutige DriveItem-ID der Datei innerhalb der SharePoint-Dokumentbibliothek.</param>
/// <param name="targetPath">
/// Lokales Zielverzeichnis für die heruntergeladene Datei.
/// Der Dateiname darf hier nicht enthalten sein.
/// </param>
/// <returns>
/// Vollständiger lokaler Dateipfad der gespeicherten Datei bei Erfolg,
/// andernfalls ein leerer String.
/// </returns>
public static string MsSharePointViaGraph_DownloadFileById(string absoluteLibraryUrl, string driveItemId, string targetPath)

Dokument Upload

/// <summary>
/// Lädt eine lokale Datei an einen angegebenen SharePoint-Zielordner hoch
/// und gibt die DriveItem-ID der hochgeladenen Datei zurück.
/// </summary>
/// <remarks>
/// Der Name der Zieldatei wird immer aus dem Dateinamen von <paramref name="sourceFilePath"/> abgeleitet.
/// Existiert der angegebene Zielordner in SharePoint nicht, wird die erforderliche Ordnerstruktur automatisch erstellt.
/// Bei Fehlern oder Ausnahmen wird kein Throw ausgelöst; die Methode gibt in diesem Fall einen leeren String zurück.
/// </remarks>
/// <param name="absoluteTargetFolderUrl">
/// Absolute URL des SharePoint-Zielordners (Dokumentbibliothek oder Unterordner), in den die Datei hochgeladen wird.
/// Ein in der URL enthaltener Dateiname wird ignoriert.
/// </param>
/// <param name="sourceFilePath">Vollständiger lokaler Dateipfad der hochzuladenden Datei.</param>
/// <returns>DriveItem-ID der hochgeladenen Datei bei Erfolg, andernfalls ein leerer String.</returns>
public static string MsSharePointViaGraph_UploadFile(string absoluteTargetFolderUrl, string sourceFilePath)

DriveItem Löschen

/// <summary>
/// Löscht eine Datei oder einen Ordner anhand der DriveItem-ID aus einer SharePoint-DokumentBibliothek.
/// </summary>
/// <param name="absoluteLibraryUrl">Absolute URL der SharePoint-Dokumentbibliothek, in der sich das DriveItem befindet.</param>
/// Diese URL muss die Site sowie den Pfad zur Dokumentbibliothek enthalten.</param>
/// <param name="driveItemId">Eindeutige DriveItem-ID der zu löschenden Datei oder des Ordners.</param>
public static void MsSharePointViaGraph_DeleteDriveItemById(string absoluteLibraryUrl, string driveItemId)

Verwendete Bibliotheken

Die verwendeten Bibliotheken werden als Software Build of Material (SBOM) mit dem Release ausgeliefert. Die SBOM wird im SPDX-Format 2.2 zur Verfügung gestellt und liegt parallel zum Release.

letzte Änderung: 20.01.2026