Entwickeln mit SharePoint 2010-Word Automation Services

Zusammenfassung: Lernen Sie, wie Sie mithilfe von Word Automation Services serverseitige Dokumentkonvertierungen in und aus verschiedene(n) Formate(n) durchführen. Mit dem Open XML SDK können Sie auch schwierige Aufgaben durchführen, beispielsweise das Aktualisieren des Inhaltsverzeichnisses oder das Paginieren von Dokumenten.

Letzte Änderung: Montag, 9. März 2015

Gilt für: Business Connectivity Services | Office 2010 | Open XML | SharePoint Designer 2010 | SharePoint Foundation 2010 | SharePoint Online | SharePoint Server 2010 | Visual Studio | Word Autmomation Services

Inhalt dieses Artikels
Ändern von Dokumentformaten mithilfe von Word Automation Services
Ein Szenario für Word Automation Services
Funktionsweise von Word Automation Services
Konfigurieren von Word Automation Services
Erstellen einer Word Automation Services-Anwendung
Überwachen des Konvertierungsstatus
Identifizieren von Dokumenten, die nicht konvertiert wurden
Löschen der Quelldateien nach der Konvertierung
Integrieren mit dem Open XML SDK
Schlussbemerkung
Weitere Ressourcen

Bereitgestellt von:Eric White, Microsoft Corporation | Tristan Davis, Microsoft Corporation | Zeyad Rajabi, Microsoft Corporation

Inhalt

• Ändern von Dokumentformaten mithilfe von Word Automation Services

• Ein Szenario für Word Automation Services

• Funktionsweise von Word Automation Services

• Erstellen einer Word Automation Services-Anwendung

• Überwachen des Konvertierungsstatus

• Identifizieren von Dokumenten, die nicht konvertiert wurden

• Löschen der Quelldateien nach der Konvertierung

• Integrieren mit dem Open XML SDK

• Schlussbemerkung

• Weitere Ressourcen

  Code zum Herunterladen

Ändern von Dokumentformaten mithilfe von Word Automation Services

Bestimmte Aufgaben lassen sich mit dem Willkommen beim Open XML SDK 2.0 für Microsoft Office nur schwer durchführen, beispielsweise das Paginieren, das Konvertieren in andere Dokumentformate wie PDF oder das Aktualisieren von Inhaltsverzeichnissen, Feldern und anderen dynamischen Dokumentinhalten. Die Word-Automatisierungsdienste sind ein neues Feature in SharePoint 2010, das in diesen Szenarien hilfreich sein kann. Es handelt sich dabei um einen gemeinsamen Dienst, der die unbeaufsichtigte serverseitige Konvertierung von Dokumenten in ein anderes Format ermöglicht und eine Reihe weiterer wichtiger Funktionalitäten bietet. Er wurde von vornherein für die Ausführung auf Servern konzipiert und kann eine große Zahl von Dokumenten zuverlässig und vorhersagbar verarbeiten.

Mithilfe der Word-Automatisierungsdienste können Sie Dokumente im Open XML-WordprocessingML-Format in andere Dokumentformate konvertieren. Beispielsweise können Sie zahlreiche Dokumente ins PDF-Format konvertieren und an einen Drucker spoolen oder per E-Mail an Ihre Kunden senden. Ebenso können Sie Dokumente aus anderen Formaten (z. B. HTML- oder Word 97-2003-Dokumente im Binärformat) in Open XML-Textverarbeitungsdokumente konvertieren.

Neben den Dokumentkonvertierungsfunktionen gibt es noch weitere wichtige Funktionsbereiche in den Word-Automatisierungsdiensten, beispielsweise das Aktualisieren von Feldcodes in Dokumenten und das Konvertieren von altChunk-Inhalten in Absätze mit der Absatzvorlage "Normal". Diese Aufgaben lassen sich mit dem Open XML SDK 2.0 kaum bewältigen. Mit den Word-Automatisierungsdiensten sind sie jedoch ganz einfach. In der Vergangenheit haben Sie mit den Word-Automatisierungsdiensten derartige Aufgaben für Clientanwendungen ausgeführt. Diese Vorgehensweise ist jedoch problematisch. Der Word-Client ist eine Anwendung, die am besten für das interaktive Erstellen von Dokumenten geeignet ist und nicht für die volumenintensive Verarbeitung auf einem Server konzipiert wurde. Während dieser Aufgaben wird in Word möglicherweise ein Dialogfenster mit einer Fehlermeldung angezeigt. Wenn der Word-Client auf einem Server automatisiert wurde, ist kein Benutzer anwesend, der auf das Dialogfeld reagieren könnte, sodass der Prozess vorzeitig beendet werden könnte. Die Probleme in Verbindung mit der Automatisierung von Word sind im Knowledge Base-Artikel Was bei der serverseitigen Automatisierung von Office zu beachten ist dokumentiert.

Ein Szenario für Word Automation Services

In diesem Szenario wird die Verwendung der Word-Automatisierungsdienste zur Automatisierung der Dokumentverarbeitung auf einem Server beschrieben.

• Eine Expertin erstellt einige Word-Vorlagendokumente nach bestimmten Konventionen. Mithilfe von Inhaltssteuerelementen könnte sie den Vorlagendokumenten Struktur verleihen. Dies sorgt für ein gutes Benutzererlebnis und eine zuverlässige programmgesteuerte Vorgehensweise zur Ermittlung der Stellen im Vorlagendokument, an denen während der Dokumentgenerierung Daten ersetzt werden sollen. Diese Vorlagendokumente werden in der Regel in einer SharePoint-Dokumentbibliothek gespeichert.

• Ein Programm auf dem Server führt die Vorlagendokumente mit Daten zusammen und generiert einen Satz von Open XML-WordprocessingML-Dokumenten (DOCX). Dieses Programm lässt sich am besten mit dem Willkommen beim Open XML SDK 2.0 für Microsoft Office erstellen, das speziell für das Generieren von Dokumenten auf einem Server konzipiert wurde. Diese Dokumente werden in einer SharePoint-Dokumentbibliothek abgelegt.

• Nachdem die Dokumente generiert wurden, können sie automatisch gedruckt werden. Sie können aber auch per E-Mail an eine Gruppe von Benutzern gesendet werden, entweder als WordprocessingML-Dokumente oder als PDF-, XPS- oder MHTML-Dokumente. Dazu müssen sie allerdings zuerst aus dem WordprocessingML-Format in das gewünschte Format konvertiert werden.

• Sie können in den Word-Automatisierungsdiensten festlegen, dass im Rahmen der Konvertierung Felder wie das Inhaltsverzeichnis aktualisiert werden.

Durch die Verwendung des Willkommen beim Open XML SDK 2.0 für Microsoft Office zusammen mit den Word-Automatisierungsdiensten können Sie reichhaltige End-to-End-Lösungen entwickeln, die eine gute Leistung bieten und keine Automatisierung der Word-Clientanwendung erfordern.

Einer der wichtigsten Vorteile der Word-Automatisierungsdienste ist die bedarfsgerechte Skalierbarkeit. Im Gegensatz zur Word-Clientanwendung können Sie die Software für mehrere Prozessoren konfigurieren. Außerdem können Sie bei Bedarf einen Lastenausgleich zwischen mehreren Servern einrichten.

Ein weiterer wesentlicher Vorteil ist die perfekte Originaltreue der Word-Automatisierungsdienste gegenüber den Word-Clientanwendungen. Das Dokumentlayout einschließlich der Paginierung ist immer gleich, unabhängig davon, ob das Dokument auf dem Server oder auf dem Client verarbeitet wurde.

Unterstützte Quelldokumentformate

Die folgenden Quelldokumentformate werden unterstützt:

1. Dokumente im Open XML-Dateiformat (DOCX, DOCM, DOTX, DOTM)

2. Word 97-2003-Dokumente (.doc, .dot)

3. Rich Text Format-Dateien (RTF)

4. Webseite in einer Datei (MHT, MHTML).

5. XML-Format (Word 2003-XML-Dokument)

6. Word-XML-Dokument (.xml)

Unterstützte Zieldokumentformate

Neben allen unterstützten Quelldokumentformaten werden folgende Zieldokumentformate unterstützt:

1. PDF-Datei (Portable Document Format)

2. Open XML Paper Specification-Dateien (.xps)

Andere Funktionalitäten von Word Automation Services

Neben der Möglichkeit zum Laden und Speichern von Dokumenten in verschiedenen Formaten bieten die Word-Automatisierungsdienste weitere Funktionalitäten.

Sie können festlegen, dass die Word-Automatisierungsdienste das Inhaltsverzeichnis, das Rechtsgrundlagenverzeichnis und die Indexfelder aktualisieren. Dies ist beim Generieren von Dokumenten von Bedeutung. Nach dem Generieren ist es bei einem Dokument mit Inhaltsverzeichnis besonders schwierig, die Seitenpaginierung zu ermitteln und das Inhaltsverzeichnis korrekt zu aktualisieren. Die Word-Automatisierungsdienste übernehmen diese Aufgabe für Sie.

Open XML-Textverarbeitungsdokumente können verschiedene Feldtypen enthalten, sodass Sie einem Dokument dynamische Inhalte hinzufügen können. Mithilfe der Word-Automatisierungsdienste können Sie festlegen, dass alle Felder neu berechnet werden. Beispielsweise können Sie einen Feldtyp einbinden, der das aktuelle Datum in das Dokument einfügt. Wenn die Felder aktualisiert werden, wird der verknüpfte Inhalt ebenfalls aktualisiert und im Dokument an der Position des Felds das aktuelle Datum angezeigt.

Eine der leistungsfähigsten Einsatzmöglichkeiten für Inhaltssteuerelemente besteht darin, sie an XML-Elemente in einer benutzerdefinierten XML-Komponente zu binden. Eine Erklärung für gebundene Inhaltssteuerelemente sowie Links zu mehreren Ressourcen für den Einstieg finden Sie im Artikel Erstellen von Systemen zur Dokumentgenerierung aus Vorlagen mit Word 2010 und Word 2007. Sie können den Inhalt von gebundenen Inhaltssteuerelementen ersetzen, indem Sie das XML-Markup in der benutzerdefinierten XML-Komponente ersetzen. Den Hauptdokumentteil müssen Sie nicht ändern. Der Hauptdokumentteil enthält zwischengespeicherte Werte für alle gebundenen Inhaltssteuerelemente. Wenn Sie das XML-Markup in der benutzerdefinierten XML-Komponente ersetzen, werden die zwischengespeicherten Werte im Hauptdokumentteil nicht aktualisiert. Dies ist kein Problem, wenn die Benutzer diese generierten Dokumente lediglich mithilfe des Word-Clients anzeigen sollen. Wenn allerdings das WordprocessingML-Markup weiterverarbeitet werden soll, müssen Sie die zwischengespeicherten Werte im Hauptdokumentteil aktualisieren. Dies ist mit den Word-Automatisierungsdiensten möglich.

Inhalte in alternativen Formaten (wie durch das altChunk-Element dargestellt) sind eine hervorragende Möglichkeit, um HTML-Inhalte in ein WordprocessingML-Dokument zu importieren. Im Artikel Erstellen von Systemen zur Dokumentgenerierung aus Vorlagen mit Word 2010 und Word 2007 werden Inhalte in alternativen Formaten sowie deren Einsatzmöglichkeiten vorgestellt. Außerdem enthält der Artikel Links zu Themen mit ersten Schritten. Bis Sie jedoch ein Dokument mit altChunk-Elementen öffnen und speichern, enthält das Dokument HTML-Markup und kein normales WordprocessingML-Markup wie Absätze, fortlaufenden Inhalt und Textelemente. Mithilfe der Word-Automatisierungsdienste können Sie das HTML-Markup (oder andere Formen von alternativem Inhalt) importieren und in WordprocessingML-Markup mit den vertrauten WordprocessingML-Absätzen mit Formatvorlagen konvertieren.

Sie können auch in und aus Formate(n) konvertieren, die von früheren Versionen von Word verwendet wurden. Wenn Sie eine Enterprise-Anwendung für Tausende von Benutzern erstellen, ist es wahrscheinlich, dass manche Benutzer Open XML-Dokumente mit Word 2007 oder Word 2003 bearbeiten. Sie können Open XML-Dokumente konvertieren, sodass sie nur Markup und Features enthalten, die von Word 2007 oder Word 2003 verwendet werden.

Einschränkungen von Word Automation Services

Die Word-Automatisierungsdienste enthalten keine Funktionen zum Drucken von Dokumenten. Es ist jedoch ganz einfach möglich, WordprocessingML-Dokumente in das PDF- oder XPS-Format zu konvertieren und an einen Drucker zu spoolen.

Eine Frage, die immer wieder gestellt wird, ist, ob die Word-Automatisierungsdienste verwendet werden können, ohne SharePoint Server 2010 zu kaufen und zu installieren. Die Word-Automatisierungsdienste nutzen Funktionen von SharePoint 2010 und sind ein Feature davon. Daher müssen Sie SharePoint Server 2010 kaufen und installieren, um die Software verwenden zu können. Die Word-Automatisierungsdienste sind in der Standard Edition und in der Enterprise Edition enthalten.

Funktionsweise von Word Automation Services

Standardmäßig werden die Word-Automatisierungsdienste als Dienst mit einer eigenständigen SharePoint Server 2010-Installation installiert und ausgeführt. Wenn Sie SharePoint 2010 in einer Serverfarm verwenden, müssen Sie die Word-Automatisierungsdienste explizit aktivieren.

Damit Sie die Software verwenden können, starten Sie über die Programmierschnittstelle einen Konvertierungsauftrag. Für jeden Konvertierungsauftrag geben Sie an, welche Dateien, Ordner oder Dokumentbibliotheken verarbeitet werden sollen. Je nach Konfiguration wird beim Starten eines Konvertierungsauftrags eine festgelegte Zahl von Konvertierungsprozessen auf jedem Server gestartet. Sie können angeben, wie häufig Konvertierungsaufträge gestartet werden sollen und wie viele Konvertierungen für jeden Konvertierungsprozess gestartet werden sollen. Darüber hinaus können Sie den Arbeitsspeicher in Prozent angeben, der von den Word-Automatisierungsdiensten maximal verwendet werden kann.

Mithilfe der Konfigurationseinstellungen können Sie die Word-Automatisierungsdienste so konfigurieren, dass nicht allzu viele Ressourcen auf den SharePoint-Servern belegt werden, die ja Teil Ihrer wichtigen Infrastruktur sind. Die erforderlichen Einstellungen ergeben sich daraus, wie Sie SharePoint Server verwenden möchten. Wenn Microsoft SharePoint Server ausschließlich für Dokumentkonvertierungen eingesetzt wird, sollten Sie die Einstellungen so konfigurieren, dass der Konvertierungsdienst den Großteil der Prozessorzeit verbrauchen kann. Wenn Sie den Konvertierungsdienst hingegen für Hintergrundkonvertierungen mit niedriger Priorität verwenden, sollten Sie ihn entsprechend konfigurieren.

Wichtig

Die Anzahl der Arbeitsprozesse sollte um mindestens eins kleiner sein als die Zahl der Prozessoren auf dem Server. Bei einem Server mit vier Prozessoren sollten Sie also maximal drei Arbeitsprozesse festlegen. Bei einer Serverfarminstallation sollte die Anzahl der Arbeitsprozesse um eins niedriger als die Zahl der Prozessoren auf dem Server mit den wenigsten Prozessoren in der Serverfarm sein. Wir empfehlen, das System für maximal 90 Dokumentkonvertierungen pro Arbeitsprozess und Minute zu konfigurieren.

Zusätzlich zu Code zum Starten von Konvertierungsprozessen können Sie auch Code zur Überwachung des Konvertierungsfortschritts schreiben. Damit können Sie die Benutzer informieren oder Benachrichtigungsergebnisse veröffentlichen, wenn extrem umfangreiche Konvertierungsaufträge abgeschlossen sind.

In den Word-Automatisierungsdiensten können Sie vier weitere Aspekte für Konvertierungen konfigurieren.

1. Sie können die Zahl der unterstützten Dateiformate einschränken.

2. Sie können angeben, wie viele Dokumente von einem Konvertierungsprozess konvertiert werden, bevor dieser neu gestartet wird. Dies ist deshalb nützlich, weil ungültige Dokumente zur Folge haben können, dass die Word-Automatisierungsdienste zu viel Arbeitsspeicher belegen. Beim Neustart des Prozesses wird der gesamte Arbeitsspeicher wieder freigegeben.

3. Sie können angeben, wie viele Konvertierungsversuche von den Word-Automatisierungsdiensten für ein Dokument unternommen werden. Standardmäßig sind dies zwei Versuche. Schlägt also ein Konvertierungsversuch für ein Dokument fehl, versuchen die Word-Automatisierungsdienste (in diesem Konvertierungsauftrag) nur noch ein weiteres Mal, das Dokument zu konvertieren.

4. Sie können angeben, wie viel Zeit vergehen soll, bevor Konvertierungsprozesse überwacht werden. Dies ist nützlich, weil Konvertierungen von den Word-Automatisierungsdiensten überwacht werden, um sicherzustellen, dass keine Konvertierungen hängen geblieben sind.

Konfigurieren von Word Automation Services

Sofern Sie keine Serverfarm installiert haben, werden die Word-Automatisierungsdienste standardmäßig in SharePoint Server 2010 installiert und gestartet. Als Entwickler sollten Sie die Konfiguration jedoch so anpassen, dass die Entwicklungsarbeit für Sie möglichst angenehm ist. Standardmäßig werden Konvertierungsprozesse in einem 15-Minuten-Intervall gestartet. Beim Testen von Code kann es sinnvoll sein, das Intervall auf eine Minute festzulegen. Außerdem gibt es Szenarien, in denen es wünschenswert ist, dass die Word-Automatisierungsdienste möglichst viele Ressourcen verwenden. Auch in diesen Fällen kann ein Intervall von einer Minute sinnvoll sein.

So stellen Sie das Intervall für den Konvertierungsprozess auf eine Minute ein

1. Starten Sie die SharePoint 2010-Zentraladministration.

2. Klicken Sie auf der Homepage der SharePoint 2010-Zentraladministration auf Dienstanwendungen verwalten.

3. Auf der Seite für die Verwaltung von Dienstanwendungen werden die Dienstanwendungen in alphabetischer Reihenfolge aufgeführt. Führen Sie auf der Seite einen Bildlauf nach ganz unten aus, und klicken Sie dann auf Word Automation Services. Wenn Sie eine Serverfarm installieren und die Word-Automatisierungsdienste manuell installiert haben, wird auf dieser Seite der Name des Dienstes so angezeigt, wie Sie ihn bei der Installation eingegeben haben.

4. Legen Sie auf der Verwaltungsseite der Word-Automatisierungsdienste als Konvertierungsdurchsatz die gewünschte Häufigkeit für das Starten von Konvertierungsaufträgen fest.

5. Als Entwickler sollten Sie außerdem die Anzahl der Konvertierungsprozesse festlegen und die Zahl der Konvertierungen pro Arbeitsprozess anpassen. Wenn Sie die Häufigkeit ändern, mit der Konvertierungsprozesse gestartet werden, ohne die beiden anderen Werte anzupassen, und dann versuchen, zahlreiche Dokumente zu konvertieren, ist der Konvertierungsprozess deutlich weniger effizient. Der optimale Wert für diese beiden Einstellungen berücksichtigt die Leistung des Computers mit SharePoint Server 2010.

6. Führen Sie auf der Seite einen Bildlauf nach ganz unten aus, und klicken Sie dann auf OK.

Erstellen einer Word Automation Services-Anwendung

Weil die Word-Automatisierungsdienste ein Dienst von SharePoint Server 2010 sind, können Sie sie nur in einer Anwendung verwenden, die direkt auf einem Computer SharePoint Server ausgeführt wird. Sie müssen die Anwendung als Farmlösung erstellen. Sie können die Word-Automatisierungsdienste nicht aus einer Lösung mit eingeschränkter Sicherheitsstufe heraus verwenden.

Eine komfortable Möglichkeit, die Word-Automatisierungsdienste zu verwenden, besteht darin, einen Webdienst zu erstellen, der von Clientanwendungen genutzt werden kann.

Am einfachsten lässt sich das Schreiben von Code für die Word-Automatisierungsdienste anhand einer Konsolenanwendung verdeutlichen. Sie müssen die Konsolenanwendung auf dem Computer mit SharePoint Server ausführen, nicht auf einem Clientcomputer. Der Code zum Starten und Überwachen von Konvertierungsaufträgen stimmt mit dem Code überein, den Sie für ein Webpart, einen Workflow oder einen Ereignishandler schreiben würden. Indem wir die Verwendung der Word-Automatisierungsdienste durch eine Konsolenanwendung demonstrieren, können wir die API ohne die zusätzliche Komplexität eines Webparts bzw. eines Ereignishandlers oder Workflows erklären.

Wichtig
Die folgenden Beispielanwendungen rufen Sleep(Int32) auf. Der Status wird alle fünf Sekunden abgefragt. Wenn Sie den erstellten Code auf Produktionsservern bereitstellen wollten, wäre diese Vorgehensweise nicht ideal. In diesem Fall sollten Sie stattdessen einen Workflow mit Delay-Aktivität erstellen.

So erstellen Sie die Anwendung

1. Starten Sie Microsoft Visual Studio 2010.

2. Zeigen Sie im Menü Datei auf Neu, und klicken Sie dann auf Projekt.

3. Erweitern Sie im Dialogfeld Neues Projekt im Bereich Zuletzt verwendete Vorlagen den Eintrag Visual C#, und klicken Sie dann auf Windows.

4. Klicken Sie rechts vom Bereich Zuletzt verwendete Vorlagen auf Konsolenanwendung.

5. Standardmäßig wird in Visual Studio ein Projekt für .NET Framework 4 erstellt. Sie müssen jedoch .NET Framework 3.5 als Ziel angeben. Wählen Sie in der Liste im oberen Teil des Dialogfelds Datei öffnen den Eintrag .NET Framework 3.5.

6. Geben Sie im Feld Name den gewünschten Namen für das Projekt ein, z. B. FirstWordAutomationServicesApplication.

7. Geben Sie im Feld Speicherort den Speicherort für das Projekt ein.

   Abbildung 1. Erstellen einer Lösung im Dialogfeld 'Neues Projekt'

   

8. Klicken Sie auf OK, um die Lösung zu erstellen.

9. Standardmäßig werden in Visual Studio 2010 Projekte für x86-CPUs erstellt. Für SharePoint Server-Anwendungen müssen Sie jedoch Any CPU als Ziel angeben.

10. Wenn Sie eine Microsoft Visual C#-Anwendung erstellen, klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt. Klicken Sie dann auf Eigenschaften.

11. Klicken Sie im Fenster mit den Projekteigenschaften auf Erstellen.

12. Zeigen Sie auf die Liste Zielplattform, und wählen Sie Any CPU aus.

    Abbildung 2. Erstellen einer C#-Konsolenanwendung für 'Any CPU'

    

13. Wenn Sie eine .NET Framework-Anwendung in Microsoft Visual Basic erstellen, klicken Sie im Fenster mit den Projekteigenschaften auf Kompilieren.

    Abbildung 3. Kompilierungsoptionen für eine Visual Basic-Anwendung

    

14. Klicken Sie auf Erweiterte Kompilierungsoptionen.

    Abbildung 4. Dialogfeld 'Erweiterte Compilereinstellungen'

    

15. Zeigen Sie auf die Liste Zielplattform, und klicken Sie auf Any CPU.

16. Um einen Verweis auf die Microsoft.Office.Word.Server-Assembly hinzuzufügen, klicken Sie im Menü Projekt auf Verweis hinzufügen, um das gleichnamige Dialogfeld zu öffnen.

17. Wählen Sie die Registerkarte .NET aus, und fügen Sie die Komponente namens Microsoft Office 2010-Komponente hinzu.

    Abbildung 5. Hinzufügen eines Verweises auf eine Microsoft Office 2010-Komponente

    

18. Fügen Sie als Nächstes einen Verweis auf die Microsoft.SharePoint-Assembly hinzu.

    Abbildung 6. Hinzufügen eines Verweises auf Microsoft SharePoint

    

Die folgenden Beispiele stellen die vollständigen Auflistungen für C# und Visual Basic für die einfachste Word-Automatisierungsdienste-Anwendung bereit.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.Office.Word.Server.Conversions;

class Program
{
    static void Main(string[] args)
    {
        string siteUrl = "https://localhost";
        // If you manually installed Word automation services, then replace the name
        // in the following line with the name that you assigned to the service when
        // you installed it.
        string wordAutomationServiceName = "Word Automation Services";
        using (SPSite spSite = new SPSite(siteUrl))
        {
            ConversionJob job = new ConversionJob(wordAutomationServiceName);
            job.UserToken = spSite.UserToken;
            job.Settings.UpdateFields = true;
            job.Settings.OutputFormat = SaveFormat.PDF;
            job.AddFile(siteUrl + "/Shared%20Documents/Test.docx",
                siteUrl + "/Shared%20Documents/Test.pdf");
            job.Start();
        }
    }
}

Imports Microsoft.SharePoint
Imports Microsoft.Office.Word.Server.Conversions
Module Module1
    Sub Main()
        Dim siteUrl As String = "https://localhost"
        ' If you manually installed Word automation services, then replace the name
        ' in the following line with the name that you assigned to the service when
        ' you installed it.
        Dim wordAutomationServiceName As String = "Word Automation Services"
        Using spSite As SPSite = New SPSite(siteUrl)
            Dim job As ConversionJob = New ConversionJob(wordAutomationServiceName)
            job.UserToken = spSite.UserToken
            job.Settings.UpdateFields = True
            job.Settings.OutputFormat = SaveFormat.PDF
            job.AddFile(siteUrl + "/Shared%20Documents/Test.docx", _
                siteUrl + "/Shared%20Documents/Test.pdf")
            job.Start()
        End Using
    End Sub
End Module

Hinweis
Ersetzen Sie die URL für siteUrl durch die URL der SharePoint-Website.

So erstellen Sie das Beispiel und führen es aus

1. Fügen Sie auf der SharePoint-Website im Ordner Freigegebene Dokumente ein Word-Dokument namens Test.docx hinzu.

2. Erstellen Sie das Beispiel, und führen Sie es aus.

3. Warten Sie eine Minute, während der Konvertierungsprozess läuft, navigieren Sie zum Ordner Freigegebene Dokumente auf der SharePoint-Website, und aktualisieren Sie die Seite. In der Dokumentbibliothek befindet sich jetzt das neue PDF-Dokument Test.pdf.

Überwachen des Konvertierungsstatus

In vielen Szenarien muss der Status der Konvertierungen überwacht werden, damit der Benutzer weiß, wann der Konvertierungsprozess abgeschlossen ist, oder damit die konvertierten Dokumente weiterverarbeitet werden können. Mithilfe der ConversionJobStatus-Klasse können Sie in Word-Automatisierungsdienste den Status eines Konvertierungsauftrags abfragen. Übergeben Sie den Namen der WordServiceApplicationProxy-Klasse als Zeichenfolge (standardmäßig "Word-Automatisierungsdienste") sowie die Konvertierungsauftrags-ID, die Sie vom ConversionJob-Objekt abrufen können. Sie können auch eine GUID übergeben, die eine Mandantenpartition angibt. Wenn die SharePoint Server-Farm allerdings nicht für mehrere Mandanten konfiguriert ist, können Sie Null (Nothing in Visual Basic) als Argument für diesen Parameter übergeben.

Nachdem Sie ein ConversionJobStatus-Objekt instanziiert haben, können Sie auf mehrere Eigenschaften zugreifen, die den Status des Konvertierungsauftrags angeben. Die drei folgenden Eigenschaften sind dabei von besonderem Interesse.

ConversionJobStatus-Eigenschaften

Eigenschaft	Rückgabewert
Count	Anzahl der aktuell im Konvertierungsauftrag enthaltenen Dokumente
Succeeded	Anzahl der erfolgreich konvertierten Dokumente
Failed	Anzahl der Dokumente, die nicht konvertiert werden konnten

Während im ersten Beispiel ein einziges Dokument für die Konvertierung angegeben wurde, werden im folgenden Beispiel alle Dokumente in der angegebenen Dokumentbibliothek konvertiert. Sie haben die Möglichkeit, alle konvertierten Dokumente in einer anderen Dokumentbibliothek als der Quellbibliothek zu erstellen. Der Einfachheit halber wird im folgenden Beispiel dieselbe Dokumentbibliothek für die Eingabe und die Ausgabe verwendet. Außerdem ist festgelegt, dass das Ausgabedokument überschrieben werden soll, falls es bereits vorhanden ist.

Code zum Herunterladen

Console.WriteLine("Starting conversion job");
ConversionJob job = new ConversionJob(wordAutomationServiceName);
job.UserToken = spSite.UserToken;
job.Settings.UpdateFields = true;
job.Settings.OutputFormat = SaveFormat.PDF;
job.Settings.OutputSaveBehavior = SaveBehavior.AlwaysOverwrite;
SPList listToConvert = spSite.RootWeb.Lists["Shared Documents"];
job.AddLibrary(listToConvert, listToConvert);
job.Start();
Console.WriteLine("Conversion job started");
ConversionJobStatus status = new ConversionJobStatus(wordAutomationServiceName,
    job.JobId, null);
Console.WriteLine("Number of documents in conversion job: {0}", status.Count);
while (true)
{
    Thread.Sleep(5000);
    status = new ConversionJobStatus(wordAutomationServiceName, job.JobId,
        null);
    if (status.Count == status.Succeeded + status.Failed)
    {
        Console.WriteLine("Completed, Successful: {0}, Failed: {1}",
            status.Succeeded, status.Failed);
        break;
    }
    Console.WriteLine("In progress, Successful: {0}, Failed: {1}",
        status.Succeeded, status.Failed);
}

Console.WriteLine("Starting conversion job")
Dim job As ConversionJob = New ConversionJob(wordAutomationServiceName)
job.UserToken = spSite.UserToken
job.Settings.UpdateFields = True
job.Settings.OutputFormat = SaveFormat.PDF
job.Settings.OutputSaveBehavior = SaveBehavior.AlwaysOverwrite
Dim listToConvert As SPList = spSite.RootWeb.Lists("Shared Documents")
job.AddLibrary(listToConvert, listToConvert)
job.Start()
Console.WriteLine("Conversion job started")
Dim status As ConversionJobStatus = _
    New ConversionJobStatus(wordAutomationServiceName, job.JobId, Nothing)
Console.WriteLine("Number of documents in conversion job: {0}", status.Count)
While True
    Thread.Sleep(5000)
    status = New ConversionJobStatus(wordAutomationServiceName, job.JobId, _
                                     Nothing)
    If status.Count = status.Succeeded + status.Failed Then
        Console.WriteLine("Completed, Successful: {0}, Failed: {1}", _
                          status.Succeeded, status.Failed)
        Exit While
    End If
    Console.WriteLine("In progress, Successful: {0}, Failed: {1}", _
                      status.Succeeded, status.Failed)
End While

Bevor Sie dieses Beispiel ausführen, fügen Sie in der Bibliothek Freigegebene Dokumente einige WordprocessingML-Dokumente hinzu. Beim Ausführen des Beispiels sehen Sie eine ähnliche Ausgabe wie in folgendem Codeausschnitt.

Starting conversion job
Conversion job started
Number of documents in conversion job: 4
In progress, Successful: 0, Failed: 0
In progress, Successful: 0, Failed: 0
Completed, Successful: 4, Failed: 0

Identifizieren von Dokumenten, die nicht konvertiert wurden

Möglicherweise möchten Sie wissen, welche Dokumente nicht konvertiert werden konnten, beispielsweise, um den Benutzer darüber zu informieren oder um Gegenmaßnahmen zu treffen, indem das ungültige Dokument beispielsweise aus der Eingabedokumentbibliothek entfernt wird. Sie können die GetItems()-Methode aufrufen, die eine Auflistung von ConversionItemInfo()-Objekten zurückgibt. Wenn Sie die GetItems()-Methode aufrufen, übergeben Sie einen Parameter, der angibt, ob eine Auflistung der nicht erfolgreichen oder der erfolgreichen Konvertierungen abgerufen werden soll. Im folgenden Beispiel wird dies veranschaulicht.

Code zum Herunterladen

Console.WriteLine("Starting conversion job");
ConversionJob job = new ConversionJob(wordAutomationServiceName);
job.UserToken = spSite.UserToken;
job.Settings.UpdateFields = true;
job.Settings.OutputFormat = SaveFormat.PDF;
job.Settings.OutputSaveBehavior = SaveBehavior.AlwaysOverwrite;
SPList listToConvert = spSite.RootWeb.Lists["Shared Documents"];
job.AddLibrary(listToConvert, listToConvert);
job.Start();
Console.WriteLine("Conversion job started");
ConversionJobStatus status = new ConversionJobStatus(wordAutomationServiceName,
    job.JobId, null);
Console.WriteLine("Number of documents in conversion job: {0}", status.Count);
while (true)
{
    Thread.Sleep(5000);
    status = new ConversionJobStatus(wordAutomationServiceName, job.JobId, null);
    if (status.Count == status.Succeeded + status.Failed)
    {
        Console.WriteLine("Completed, Successful: {0}, Failed: {1}",
            status.Succeeded, status.Failed);
        ReadOnlyCollection<ConversionItemInfo> failedItems =
            status.GetItems(ItemTypes.Failed);
        foreach (var failedItem in failedItems)
            Console.WriteLine("Failed item: Name:{0}", failedItem.InputFile);
        break;
    }
    Console.WriteLine("In progress, Successful: {0}, Failed: {1}", status.Succeeded,
        status.Failed);
}

Console.WriteLine("Starting conversion job")
Dim job As ConversionJob = New ConversionJob(wordAutomationServiceName)
job.UserToken = spSite.UserToken
job.Settings.UpdateFields = True
job.Settings.OutputFormat = SaveFormat.PDF
job.Settings.OutputSaveBehavior = SaveBehavior.AlwaysOverwrite
Dim listToConvert As SPList = spSite.RootWeb.Lists("Shared Documents")
job.AddLibrary(listToConvert, listToConvert)
job.Start()
Console.WriteLine("Conversion job started")
Dim status As ConversionJobStatus = _
    New ConversionJobStatus(wordAutomationServiceName, job.JobId, Nothing)
Console.WriteLine("Number of documents in conversion job: {0}", status.Count)
While True
    Thread.Sleep(5000)
    status = New ConversionJobStatus(wordAutomationServiceName, job.JobId, _
                                     Nothing)
    If status.Count = status.Succeeded + status.Failed Then
        Console.WriteLine("Completed, Successful: {0}, Failed: {1}", _
                          status.Succeeded, status.Failed)
        Dim failedItems As ReadOnlyCollection(Of ConversionItemInfo) = _
            status.GetItems(ItemTypes.Failed)
        For Each failedItem In failedItems
            Console.WriteLine("Failed item: Name:{0}", failedItem.InputFile)
        Next
        Exit While
    End If
    Console.WriteLine("In progress, Successful: {0}, Failed: {1}", _
                      status.Succeeded, status.Failed)
End While

Bevor Sie dieses Beispiel ausführen, erstellen Sie ein ungültiges Dokument, und laden Sie es in die Dokumentbibliothek hoch. Am einfachsten erstellen Sie ein ungültiges Dokument, indem Sie das WordprocessingML-Dokument umbenennen und die Dateierweiterung .zip an den Dateinamen anhängen. Löschen Sie dann den Hauptdokumentteil (document.xml), der sich im Word-Ordner des Pakets befindet. Benennen Sie das Dokument um, und entfernen Sie die Dateierweiterung .zip wieder, sodass das Dokument nur noch die normale Erweiterung .docx enthält.

Beim Ausführen des Beispiels erhalten Sie eine ähnliche Ausgabe wie folgende.

Starting conversion job
Conversion job started
Number of documents in conversion job: 5
In progress, Successful: 0, Failed: 0
In progress, Successful: 0, Failed: 0
In progress, Successful: 4, Failed: 0
In progress, Successful: 4, Failed: 0
In progress, Successful: 4, Failed: 0
Completed, Successful: 4, Failed: 1
Failed item: Name:http://intranet.contoso.com/Shared%20Documents/IntentionallyInvalidDocument.docx

Eine weitere Möglichkeit zum Überwachen eines Konvertierungsprozesses besteht darin, mithilfe von Ereignishandlern in einer SharePoint-Liste zu ermitteln, wann ein konvertiertes Dokument zur Ausgabedokumentbibliothek hinzugefügt wird.

Löschen der Quelldateien nach der Konvertierung

In manchen Situationen müssen Sie die Quelldokumente nach der Konvertierung löschen. Im folgenden Beispiel wird dies veranschaulicht.

Code zum Herunterladen

Console.WriteLine("Starting conversion job");
ConversionJob job = new ConversionJob(wordAutomationServiceName);
job.UserToken = spSite.UserToken;
job.Settings.UpdateFields = true;
job.Settings.OutputFormat = SaveFormat.PDF;
job.Settings.OutputSaveBehavior = SaveBehavior.AlwaysOverwrite;
SPFolder folderToConvert = spSite.RootWeb.GetFolder("Shared Documents");
job.AddFolder(folderToConvert, folderToConvert, false);
job.Start();
Console.WriteLine("Conversion job started");
ConversionJobStatus status = new ConversionJobStatus(wordAutomationServiceName,
    job.JobId, null);
Console.WriteLine("Number of documents in conversion job: {0}", status.Count);
while (true)
{
    Thread.Sleep(5000);
    status = new ConversionJobStatus(wordAutomationServiceName, job.JobId, null);
    if (status.Count == status.Succeeded + status.Failed)
    {
        Console.WriteLine("Completed, Successful: {0}, Failed: {1}",
            status.Succeeded, status.Failed);
        Console.WriteLine("Deleting only items that successfully converted");
        ReadOnlyCollection<ConversionItemInfo> convertedItems =
            status.GetItems(ItemTypes.Succeeded);
        foreach (var convertedItem in convertedItems)
        {
            Console.WriteLine("Deleting item: Name:{0}", convertedItem.InputFile);
            folderToConvert.Files.Delete(convertedItem.InputFile);
        }
        break;
    }
    Console.WriteLine("In progress, Successful: {0}, Failed: {1}",
        status.Succeeded, status.Failed);
}

Console.WriteLine("Starting conversion job")
Dim job As ConversionJob = New ConversionJob(wordAutomationServiceName)
job.UserToken = spSite.UserToken
job.Settings.UpdateFields = True
job.Settings.OutputFormat = SaveFormat.PDF
job.Settings.OutputSaveBehavior = SaveBehavior.AlwaysOverwrite
Dim folderToConvert As SPFolder = spSite.RootWeb.GetFolder("Shared Documents")
job.AddFolder(folderToConvert, folderToConvert, False)
job.Start()
Console.WriteLine("Conversion job started")
Dim status As ConversionJobStatus = _
    New ConversionJobStatus(wordAutomationServiceName, job.JobId, Nothing)
Console.WriteLine("Number of documents in conversion job: {0}", status.Count)
While True
    Thread.Sleep(5000)
    status = New ConversionJobStatus(wordAutomationServiceName, job.JobId, _
                                     Nothing)
    If status.Count = status.Succeeded + status.Failed Then
        Console.WriteLine("Completed, Successful: {0}, Failed: {1}", _
                          status.Succeeded, status.Failed)
        Console.WriteLine("Deleting only items that successfully converted")
        Dim convertedItems As ReadOnlyCollection(Of ConversionItemInfo) = _
            status.GetItems(ItemTypes.Succeeded)
        For Each convertedItem In convertedItems
            Console.WriteLine("Deleting item: Name:{0}", convertedItem.InputFile)
            folderToConvert.Files.Delete(convertedItem.InputFile)
        Next
        Exit While
    End If
    Console.WriteLine("In progress, Successful: {0}, Failed: {1}",
                      status.Succeeded, status.Failed)
End While

Integrieren mit dem Open XML SDK

Die Stärken der Word-Automatisierungsdienste treten dann besonders stark zu Tage, wenn Sie sie in Verbindung mit dem Willkommen beim Open XML SDK 2.0 für Microsoft Office verwenden. Sie können ein Dokument in einer Dokumentbibliothek mithilfe des Willkommen beim Open XML SDK 2.0 für Microsoft Office programmgesteuert ändern und dann mithilfe der Word-Automatisierungsdienste eine der schwierigen Aufgaben im Open XML SDK durchführen. Häufig ist es notwendig, ein Dokument programmgesteuert zu generieren und dann das Inhaltsverzeichnis dieses Dokuments zu generieren oder zu aktualisieren. Ein Beispiel wäre folgendes Dokument, das ein Inhaltsverzeichnis enthält.

Abbildung 7. Dokument mit Inhaltsverzeichnis

Angenommen, Sie möchten dieses Dokument ändern und Inhalte hinzufügen, die im Inhaltsverzeichnis enthalten sein sollen. Im nächsten Beispiel werden die folgenden Schritte ausgeführt.

1. Öffnen der Website und Abrufen des Dokuments Test.docx mithilfe einer Collaborative Application Markup Language (CAML)-Abfrage

2. Öffnen des Dokuments unter Verwendung des Open XML SDK 2.0 und Hinzufügen eines neuen Absatzes mit der Absatzvorlage Überschrift 1 am Anfang des Dokuments

3. Starten eines Konvertierungsauftrags, mit dem Test.docx in TestWithNewToc.docx konvertiert wird; nach Abschluss der Konvertierung erfolgt die Rückmeldung, ob die Konvertierung erfolgreich war

Code zum Herunterladen

Console.WriteLine("Querying for Test.docx");
SPList list = spSite.RootWeb.Lists["Shared Documents"];
SPQuery query = new SPQuery();
query.ViewFields = @"<FieldRef Name='FileLeafRef' />";
query.Query =
  @"<Where>
      <Eq>
        <FieldRef Name='FileLeafRef' />
        <Value Type='Text'>Test.docx</Value>
      </Eq>
    </Where>";
SPListItemCollection collection = list.GetItems(query);
if (collection.Count != 1)
{
    Console.WriteLine("Test.docx not found");
    Environment.Exit(0);
}
Console.WriteLine("Opening");
SPFile file = collection[0].File;
byte[] byteArray = file.OpenBinary();
using (MemoryStream memStr = new MemoryStream())
{
    memStr.Write(byteArray, 0, byteArray.Length);
    using (WordprocessingDocument wordDoc =
        WordprocessingDocument.Open(memStr, true))
    {
        Document document = wordDoc.MainDocumentPart.Document;
        Paragraph firstParagraph = document.Body.Elements<Paragraph>()
            .FirstOrDefault();
        if (firstParagraph != null)
        {
            Paragraph newParagraph = new Paragraph(
                new ParagraphProperties(
                    new ParagraphStyleId() { Val = "Heading1" }),
                new Run(
                    new Text("About the Author")));
            Paragraph aboutAuthorParagraph = new Paragraph(
                new Run(
                    new Text("Eric White")));
            firstParagraph.Parent.InsertBefore(newParagraph, firstParagraph);
            firstParagraph.Parent.InsertBefore(aboutAuthorParagraph,
                firstParagraph);
        }
    }
    Console.WriteLine("Saving");
    string linkFileName = file.Item["LinkFilename"] as string;
    file.ParentFolder.Files.Add(linkFileName, memStr, true);
}
Console.WriteLine("Starting conversion job");
ConversionJob job = new ConversionJob(wordAutomationServiceName);
job.UserToken = spSite.UserToken;
job.Settings.UpdateFields = true;
job.Settings.OutputFormat = SaveFormat.Document;
job.AddFile(siteUrl + "/Shared%20Documents/Test.docx",
    siteUrl + "/Shared%20Documents/TestWithNewToc.docx");
job.Start();
Console.WriteLine("After starting conversion job");
while (true)
{
    Thread.Sleep(5000);
    Console.WriteLine("Polling...");
    ConversionJobStatus status = new ConversionJobStatus(
        wordAutomationServiceName, job.JobId, null);
    if (status.Count == status.Succeeded + status.Failed)
    {
        Console.WriteLine("Completed, Successful: {0}, Failed: {1}",
            status.Succeeded, status.Failed);
        break;
    }
}

Console.WriteLine("Querying for Test.docx")
Dim list As SPList = spSite.RootWeb.Lists("Shared Documents")
Dim query As SPQuery = New SPQuery()
query.ViewFields = "<FieldRef Name='FileLeafRef' />"
query.Query = ( _
   <Where>
       <Eq>
           <FieldRef Name='FileLeafRef'/>
           <Value Type='Text'>Test.docx</Value>
       </Eq>
   </Where>).ToString()
Dim collection As SPListItemCollection = list.GetItems(query)
If collection.Count <> 1 Then
    Console.WriteLine("Test.docx not found")
    Environment.Exit(0)
End If
Console.WriteLine("Opening")
Dim file As SPFile = collection(0).File
Dim byteArray As Byte() = file.OpenBinary()
Using memStr As MemoryStream = New MemoryStream()
    memStr.Write(byteArray, 0, byteArray.Length)
    Using wordDoc As WordprocessingDocument = _
        WordprocessingDocument.Open(memStr, True)
        Dim document As Document = wordDoc.MainDocumentPart.Document
        Dim firstParagraph As Paragraph = _
            document.Body.Elements(Of Paragraph)().FirstOrDefault()
        If firstParagraph IsNot Nothing Then
            Dim newParagraph As Paragraph = New Paragraph( _
                New ParagraphProperties( _
                    New ParagraphStyleId() With {.Val = "Heading1"}), _
                New Run( _
                    New Text("About the Author")))
            Dim aboutAuthorParagraph As Paragraph = New Paragraph( _
                New Run( _
                    New Text("Eric White")))
            firstParagraph.Parent.InsertBefore(newParagraph, firstParagraph)
            firstParagraph.Parent.InsertBefore(aboutAuthorParagraph, _
                                               firstParagraph)
        End If
    End Using
    Console.WriteLine("Saving")
    Dim linkFileName As String = file.Item("LinkFilename")
    file.ParentFolder.Files.Add(linkFileName, memStr, True)
End Using
Console.WriteLine("Starting conversion job")
Dim job As ConversionJob = New ConversionJob(wordAutomationServiceName)
job.UserToken = spSite.UserToken
job.Settings.UpdateFields = True
job.Settings.OutputFormat = SaveFormat.Document
job.AddFile(siteUrl + "/Shared%20Documents/Test.docx", _
    siteUrl + "/Shared%20Documents/TestWithNewToc.docx")
job.Start()
Console.WriteLine("After starting conversion job")
While True
    Thread.Sleep(5000)
    Console.WriteLine("Polling...")
    Dim status As ConversionJobStatus = New ConversionJobStatus( _
        wordAutomationServiceName, job.JobId, Nothing)
    If status.Count = status.Succeeded + status.Failed Then
        Console.WriteLine("Completed, Successful: {0}, Failed: {1}", _
                          status.Succeeded, status.Failed)
        Exit While
    End If
End While

Nach der Ausführung dieses Beispiels mit einem Dokument, das dem weiter oben in diesem Abschnitt verwendeten ähnelt, wird ein neues Dokument erzeugt, wie in Abbildung 8 dargestellt.

Abbildung 8. Dokument mit aktualisiertem Inhaltsverzeichnis

Schlussbemerkung

Die Open XML SDK 2.0 sind ein leistungsfähiges Tool für die Erstellung von serverseitigen Systemen für die Dokumentgenerierung und -verarbeitung. Einige Aspekte der Dokumentmanipulation sind jedoch sehr schwierig, u. a. Dokumentkonvertierungen sowie das Aktualisieren von Feldern, Inhaltsverzeichnissen usw. Die Word-Automatisierungsdienste schließen diese Lücke mit einer leistungsfähigen Lösung, die bedarfsgerecht skaliert werden kann. Die Verwendung des Open XML SDK 2.0 in Verbindung mit den Word-Automatisierungsdiensten macht viele Szenarien erst möglich, die mit dem Open XML SDK 2.0 allein nur schwer realisierbar sind.

Weitere Ressourcen

  Code zum Herunterladen

• Developer Center: Ressourcencenter für Open XML-Formate

• Blog: Blog von Eric White

• Blog: Word 2010-Blog

• Willkommen beim Open XML SDK 2.0 für Microsoft Office

• Erstellen von Systemen zur Dokumentgenerierung aus Vorlagen mit Word 2010 und Word 2007

• Erstellen von Veröffentlichungssystemen, die mit Word 2010 oder Word 2007 arbeiten