Kolumne: SharePoint ganz praktisch

SharePoint Server 2010-2019: Word Automation Service
Keine Kommentare

SharePoint stellt mit dem Word Automation Service einen Dienst bereit, um Microsoft-Word-Dateien serverseitig zu manipulieren. Dieser Dienst wurde mit SharePoint 2010 eingeführt und in SharePoint 2013 um eine Streamingmöglichkeit erweitert. Diese Ausgabe der Kolumne stellt den Dienst kurz vor.

Die serverseitige Verarbeitung von Dokumenten ist eine typische Herausforderung in vielen dokumentenzentrierten Prozessabläufen. Der Zugriff auf Microsoft-Word-Dateien ist dabei eine gängige Anforderung. Für den programmatischen Zugriff auf Word-Dateien stehen unterschiedlichste (Third-Party-)Bibliotheken zur Verfügung, die entweder nur Lese- oder auch Schreiboperationen zulassen. Auf diesem Wege können dann entweder nur Informationen aus einer Datei extrahiert oder auch Modifikationen vorgenommen werden. Mit SharePoint 2010 veröffentlichte Microsoft den Word Automation Service. Dieser Dienst erlaubt ebenfalls die programmatische Verarbeitung von Word-Dateien. Somit wird in vielen Fällen keine separate Programmbibliothek benötigt. Das senkt die Kosten und erleichtert die Verteilung der Lösung auf unterschiedliche Installationsziele, da keine separate DLL mit verteilt werden muss. Zudem werden dadurch unter Umständen auftretende Versionskonflikte der Programmbibliothek vermieden bzw. sie treten erst gar nicht auf.

Möglichkeiten und Funktionen

Microsoft selbst bietet für den Zugriff auf Word-Dokumente das Open XML SDK an. Das SDK enthält ebenfalls Bibliotheken, die einen interaktiven Zugriff auf Microsoft-Word-Dateien ermöglichen. Jedoch lassen sich allein mit dem SDK nicht alle Anforderungen, wie zum Beispiel das Konvertieren in andere Formate oder auch das Aktualisieren von Inhaltsverzeichnissen, einfach durchführen. Für diese und weitere Aufgaben kann der Word Automation Service verwendet werden. Dieser wurde von Anfang an für den serverseitigen Einsatz konzipiert und ist in der Lage, eine große Anzahl von Dokumenten zu verarbeiten. Abbildung 1 zeigt den schematischen Aufbau des Diensts.

Abb. 1: Architektur des Word Automation Service

Abb. 1: Architektur des Word Automation Service

Neben der Konvertierungsfunktion, mit denen Word-Dokumente beispielsweise in PDF-Dokumente überführt werden können, bietet der Dienst noch zahlreiche weitere Möglichkeiten. So können eingebettete Feldcodes, Inhaltsverzeichnisse, Rechtsgrundlagenverzeichnisse und Indexfelder aktualisiert werden. Weiterhin ermöglicht der Dienst die Festlegung des Kompatibilitätsmodus des Dokuments auf die neueste Version oder auf frühere Word-Versionen. Ebenso kann eine XML-Zuordnung getroffen werden und es können alternative Formatfragmente zusammengeführt werden. Als Eingangsformate werden die folgenden unterstützt:

  • Dokumente im Open-XML-Dateiformat (DOCX, DOCM, DOTX, DOTM),
  • Word 97-2003-Dokumente (DOC, DOT),
  • Rich-Text-Format-Dateien (RTF),
  • Webseite in einer Datei (MHT, MHTML),
  • Word-2003-XML-Dokumente (XML),
  • Word-XML-Dokumente (XML).

Geöffnete Dokumente im Dienst können wahlweise im Portable-Document-Format (PDF) oder im XML-Paper-Specification-Format (XPS) zurückgespeichert werden. Somit bietet der Dienst für die häufigsten Anforderungen bereits eine gute Unterstützung.

Erweiterungen in SharePoint 2013

Um die genannten Funktionen des Word Automation Service zu nutzen, muss ein sogenannter Konvertierungsauftrag programmatisch erstellt und SharePoint zur Abarbeitung übergeben werden. Das war in SharePoint 2010 die einzige Möglichkeit. Der Nachteil bei diesem Vorgehen ist, dass es zu Verzögerungen kommt, bis der Auftrag effektiv ausgeführt wird. Mit SharePoint 2013 wurde der Dienst erweitert und ermöglichte es von da an, eine Konvertierung auf Anforderung (On Demand) entgegenzunehmen. Somit wird der Auftrag direkt ohne Verzögerung entgegengenommen und ausgeführt. Es können unter SharePoint 2013 und späteren Versionen aber auch weiterhin Konvertierungsaufträge über den Zeitgeberdienst eingestellt werden.

C# 8.0 Spickzettel

Kostenlos: C# 8.0 – neue Sprachfeatures auf einen Blick

Der C#-8.0-Spickzettel fasst die neuen Features der Sprache zusammen mit Blick auf das aktuelle .NET Core 3.0 bzw. .NET Standard 2.1. Jetzt herunterladen und schneller & effektiver programmieren!

Das ermöglicht die einfache Weiterverwendung vorhandener Lösungen, ohne Modifikationen vornehmen zu müssen. Auch mit den neuen Lösungen lässt sich weiterhin der klassische Weg verwenden und können Aufträge über die Warteschlange eingestellt werden. Das ist auch zu empfehlen, wenn die Konvertierungsaufträge nicht zeitkritisch sind. Somit verbleiben dann mehr Systemressourcen für Konvertierungsaufträge, die zügig abgearbeitet werden müssen. Denn Konvertierungsaufträge, die über den neuen Auf-Anforderung-Weg (On-Demand) eingestellt werden, werden vorrangig behandelt und synchron abgearbeitet. Das bedeutet, dass die Bearbeitung der Aufträge, die über die Auftragswarteschlange eingestellt werden, unterbrochen und angehalten wird. Anschließend werden zunächst alle On-Demand-Konvertierungsaufträge abgearbeitet und erst danach werden die unterbrochenen Aufträge aus der Auftragswarteschlange fortgesetzt. Daher ist es wichtig, nur wirklich wichtige Konvertierungsaufträge über den neuen Weg in Auftrag zu geben.

Einrichtung des Diensts

Wenn der Dienst noch nicht während der SharePoint-Farm-Installation angelegt wurde, muss er im Vorfeld installiert und konfiguriert werden. Die Einrichtung kann entweder über die Zentraladministration oder über PowerShell erfolgen.

Widmen wir uns zunächst der Einrichtung über die SharePoint-Zentraladministration. Nachdem sie geöffnet wurde, muss aus den linken Navigationspunkten der Punkt Application Management aufgerufen und auf der nachfolgenden Seite der Link Manage Service Applications angewählt werden. Anschließend findet sich im Menüband (Ribbon) der Punkt New, der beim Öffnen die verfügbaren Dienstanwendungen anzeigt. Aus den dort verfügbaren Diensten muss am Ende der Word Automation Service aktiviert werden. Danach erscheint der Dialog in Abbildung 2. Hier sind nur wenige Informationen zu erfassen. Im oberen Feld Name ist ein frei wählbarer Bezeichner für den Dienst einzutragen. Dann kann entweder ein bestehender IIS-Anwendungspool verwendet oder ein neuer dedizierter Anwendungspool erstellt werden. Zusätzlich kann noch festgelegt werden, ob ein Proxy für den Dienst erstellt werden soll.

Abb. 2: Start-Einrichtung des Word Automation Service

Nachdem alle diese Angaben getätigt wurden, wechselt man über die Schaltfläche Next zum nächsten und bereits letzten Schritt, in dem dann noch Angaben für die Dienstdatenbank vorgenommen werden müssen (Abb. 3). Der Datenbankname ist wieder frei wählbar und die Verbindung kann entweder über die empfohlene integrierte Windows-Authentifizierung oder über einen SQL-Benutzer erfolgen. Ist soweit alles erfasst, kann das Anlegen über die Schaltfläche Ok abgeschlossen werden, und der Dienst steht zur Verfügung.

Abb. 3: Angabe der Datenbankinformationen

Alternativ ist natürlich auch die Dienstkonfiguration über PowerShell einfach möglich. Dazu sind die in Listing 1 gezeigten Kommandos auszuführen. Hier finden sich die gleichen Angaben wieder, die auch bei der Erstellung über die Zentraladministration benötigt wurden. Nachdem das Kommando ausgeführt wurde, legt SharePoint den Dienst gemäß Angaben an. Im Folgenden wird anhand eines Beispiels demonstriert, wie der Dienst programmatisch verwendet werden kann.

# Anlage von Variablen für die Erstellung
$AppPoolName = "DefaultAppPool"
$SAName = "Word Konvertierungen"
$DBName = "SPWordConverterDB"
$DBServer = "SP2019DEVZHOU\SP2019SQL"
# Erstellung Service Application
$newSPWordConversionServiceApplicationSplat = @{
  DatabaseName = $DBName
  Default = $true
  ApplicationPool = $AppPoolName
  Name = $SAName
  DatabaseServer = $DBServer
}
New-SPWordConversionServiceApplication @newSPWordConversionServiceApplicationSplat;

Konvertierungsauftrag erstellen

Konvertierungsaufträge können entweder über eine eigene SharePoint-Lösung oder auch über PowerShell gestartet werden. Um den Dienst nach der Einrichtung zunächst zu testen, geht das am einfachsten und schnellsten über ein kleines PowerShell-Skript. Listing 2 zeigt dazu ein entsprechendes Testskript. Hier wird aus einer SharePoint-Bibliothek ein Dokument an den Dienst übergeben und eine Konvertierung in ein PDF-Dokument in Auftrag gegeben. Die erstellte PDF-Version wird anschließend wieder zurück in eine SharePoint-Bibliothek gespeichert. Nachdem das Kommando abgesetzt wurde, wird der Auftrag eingestellt und nach wenigen Minuten – abhängig vom Intervall des Zeitgeberdiensts – verarbeitet. Nach erfolgreicher Ausführung findet man dann in der Ablagebibliothek das erstellte PDF-Dokument wieder.

Add-PSSnapin Microsoft.SharePoint.Powershell -ErrorAction SilentlyContinue
$wordFile="http://sp2019devzhou/Shared%20Documents/Test-Doc.docx"
$date = Get-Date -format yyyy_MM
$pdfFile="http://sp2019devzhou/Shared%20Documents/WordDocument"+$date+".pdf"
# Create the conversion job
$jobSettings = New-Object Microsoft.Office.Word.Server.Conversions.ConversionJobSettings
$jobSettings.OutputFormat = "PDF"
$conversionJob = New-Object Microsoft.Office.Word.Server.Conversions.ConversionJob("Word Converter", $jobSettings)
# Get the web url
$web = Get-SPWeb "http://sp2019devzhou"
# Set the credentials to use when running the conversion job.
$conversionJob.UserToken = $web.CurrentUser.UserToken
# Conversion job name
$conversionJob.Name = "Test Konvertierung Word nach PDF"
$conversionJob.Settings.OutputFormat = [Microsoft.Office.Word.Server.Conversions.SaveFormat]::PDF
$conversionJob.AddFile($wordFile,$pdfFile)
# Start the conversion job
$conversionJob.Start()

Der zweite mögliche Weg führt über das SharePoint-Objektmodell. Listing 3 zeigt ein Beispiel basierend auf einem einfachen C#-Konsolenprogramm. Damit das Programm kompiliert werden kann, müssen die Bibliotheken Microsoft.SharePoint, Microsoft.Office.Word.Server und System.Web referenziert werden. Wie aus Listing 3 hervorgeht, wird zunächst ein SharePoint Web geöffnet. Danach wird – analog zum PowerShell-Skript – ein Konvertierungsauftrag definiert und gestartet. Nach erfolgreicher Ausführung findet man dann nach einiger Zeit das konvertierte Dokument in der angegebenen SharePoint-Bibliothek wieder.

public static void CreateWordConvertJob()
{
  using (SPSite site = new SPSite("http://sp2019devzhou/"))
  {
    using (SPWeb web = site.OpenWeb())
    {
      ConversionJobSettings jobSettings = new ConversionJobSettings();
      jobSettings.OutputSaveBehavior = SaveBehavior.AlwaysOverwrite;
      jobSettings.OutputFormat = SaveFormat.PDF;                    
      ConversionJob conversionJob = new 
      ConversionJob("Word Converter", jobSettings);
      conversionJob.Name = "Konvertierung WORD nach PDF";
      conversionJob.UserToken = web.CurrentUser.UserToken;
      conversionJob.AddFile("http://sp2019devzhou/Shared%20Documents/Test-Doc.docx", "http://sp2019devzhou/Shared%20Documents/Test-Doc-API.pdf");
      conversionJob.Start();
      Console.WriteLine("Done!");
    }
  }
}

On demand in SharePoint ab 2013

Bei den bisher demonstrierten Konvertierungen fällt auf, dass die Konvertierung aufgrund der zeitgesteuerten Ausführung einige Zeit in Anspruch nimmt, bevor das konvertierte Dokument verfügbar ist. Wie bereits zu Beginn erläutert, steht ab SharePoint 2013 ein weiterer Weg bereit, um zeitkritische Konvertierung direkt durchführen zu lassen. Listing 4 zeigt die dazugehörige Vorgehensweise. Der Aufbau ähnelt der Implementierung aus Listing 3 mit dem Zusatz, dass hier nun die Klasse SyncConverter zum Einsatz kommt, die eine synchrone Konvertierung durchführt. Ein weiterer Vorteil liegt hier in der direkten Statusverfügbarkeit. Am Ende gibt die Konvertierungsmethode direkt Informationen über das Ergebnis der Konvertierung zurück. Somit kann hier im Fehlerfall direkt reagiert werden.

public static void CreateWordConvertJobSync()
{
  using (SPSite site = new SPSite("http://sp2019devzhou/"))
  {
    using (SPWeb web = site.OpenWeb())
    {
      SyncConverter converter = new SyncConverter("Word Converter");
      converter.UserToken = web.CurrentUser.UserToken;
      converter.Settings.OutputFormat = SaveFormat.PDF;
      ConversionItemInfo result = converter.Convert("http://sp2019devzhou/Shared%20Documents/Test-Doc.docx", "http://sp2019devzhou/Shared%20Documents/Test-Doc-SYNC.pdf");
    }
  }
}

Zusammenfassung

Der SharePoint-Dienst Word Automation Service eignet sich immer dann gut, wenn serverseitige Word-Dateien verarbeitet werden müssen. Gerade die Konvertierung in Formate wie PDF ist eine häufige Anforderung. Erstellt man Lösungen für SharePoint, braucht es dann hierfür nicht noch separat eine zusätzliche Bibliothek oder einen zusätzlichen Onlinedienst.

Windows Developer

Windows DeveloperDieser Artikel ist im Windows Developer erschienen. Windows Developer informiert umfassend und herstellerneutral über neue Trends und Möglichkeiten der Software- und Systementwicklung rund um Microsoft-Technologien.

Natürlich können Sie den Windows Developer über den entwickler.kiosk auch digital im Browser oder auf Ihren Android- und iOS-Devices lesen. Außerdem ist der Windows Developer weiterhin als Print-Magazin im Abonnement erhältlich.

Unsere Redaktion empfiehlt:

Relevante Beiträge

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
400
  Subscribe  
Benachrichtige mich zu:
X
- Gib Deinen Standort ein -
- or -