MSDN Magazin > Home > Ausgaben > 2009 > MSDN Magazin Oktober 2009 > Generieren von Dokumenten aus SharePoint mit Op...

Inhalt anzeigen: Englisch mit deutscher Übersetzung

Dies sind maschinell übersetzte Inhalte, die von den Mitgliedern der Community bearbeitet werden können. Sie können die Übersetzung verbessern, indem Sie auf den jeweils zum Satz gehörenden Link "Bearbeiten" klicken.Mithilfe des Dropdown-Steuerelements "Inhalt anzeigen" links oben auf der Seite können Sie zudem bestimmen, ob nur der englische Originaltext, nur die deutsche Übersetzung oder beides nebeneinander angezeigt werden.

SharePoint and Open XML

Generating Documents from SharePoint with Open XML Content Controls

Eric White

Download the Code Sample

It's often the case that a department manager needs to regularly send a nicely formatted status report to her general manager or that a team leader needs to send a weekly status report to a number of interested parties. To collaborate with others in their organizations, both the manager and the team leader can maintain status information in SharePoint lists. The question for developers is how to include the information in the lists in a document such as a status report.

Open XML, the default file format for Office 2007, is an ISO standard (documented in exacting detail in IS29500). Put simply, Open XML files are Zip files that contain XML, and it is very easy to generate or modify Open XML documents programmatically. All you need is a library to open a Zip file and an XML API. Using the programmability features of Open XML and SharePoint, you can put together a small document-generation system that takes advantage of Open XML content controls and puts people like the manager and team leader in charge of their reports. In this article, I'll present some guidance and sample code for creating a document-generation system that uses SharePoint lists to populate tables in an Open XML word-processing document.

Overview of the Example

The example in this article is a small SharePoint Web Part that generates an Open XML word-processing document from data that lives in SharePoint lists. I've created two custom SharePoint lists, shown in Figure 1, that contain the data we want to insert into the tables.

Figure 1 Two Custom SharePoint Lists

I've also created a template Open XML word-processing document that contains content controls defining the lists and columns that are the source of the data for the generated document. The controls are shown in Figure 2.

Figure 2 The Template Open XML Document That Contains Content Controls

Finally, I created a Web Part that retrieves the list of template documents from a specific document library and presents the list to users. A user selects an item in the list and then clicks the Generate Report button. The Web Part creates an Open XML word-processing document, places it in the Reports document library, and redirects the user to that library so that she can open the report. The Web Part is shown in Figure 3, and the document it generates is shown in Figure 4.

Figure 3 A SharePoint Web Part That Allows Users to Select a Template Document

Open XML Content Controls

Before describing the SharePoint solution, I'll cover the basics of Open XML content controls. Open XML content controls provide a facility in word-processing documents that allows you to delineate content and associate metadata with that content. To use content controls, you must enable the Developer tab in Microsoft Office Word 2007. (Click Word Options on the Office menu; then, in the Word Options dialog box, select Show Developer Tab in Ribbon.)

To insert a content control, select some text and then click the button in the Controls area of the Developer tab that creates a plain text content control, shown in Figure 5.

Figure 4 An Open XML Word-Processing Document That Contains the Generated Report

Figure 5 Use This Button to Create a Plain Text Content Control

You can set properties for a content control to give it a title and assign it a tag. Click in the content control, and then click the Properties button in the Controls area on the Developer tab. This displays a dialog box you can use to set the title and the tag.

Content controls use the w:sdt element in Open XML markup, which is shown in Figure 6. The contents of the content control are defined in the w:sdtContent element. In the figure, you can also see the title of the content control in the w:alias element and the content control tag in the w:tag element.

Programming for Open XML Using the .NET Framework

You can take a variety of approaches to programming for Open XML using the Microsoft .NET Framework:

Use the classes in System.IO.Packaging
Use the Open XML SDK with any of the XML programming technologies available in .NET, including XmlDocument, XmlParser, or LINQ to XML. My favorite is LINQ to XML.
Use the strongly typed object model of the Open XML SDK version 2.0. You can find a number of articles that introduce how to program with this object model.

Here, I'm going to use the Open XML SDK (either version 1.0 or 2.0) with LINQ to XML. You can download the Open XML SDK from go.microsoft.com/fwlink/?LinkId=127912.

It is useful to encapsulate some Open XML functionality around content controls in a ContentControlManager class. When you approach the problem in this way, you can develop your Open XML functionality in a simple console application. After you have coded and debugged your Open XML functionality, you can then incorporate it in your SharePoint feature with a minimum of effort. It's pretty time-consuming to incur the overhead of deploying the SharePoint feature while debugging Open XML code.

For our SharePoint document-generation example, we want to write some code that retrieves a template document from a specific document library, queries the document for the content controls it contains and uses the metadata stored in each content control to populate the document with data from the appropriate SharePoint list.

If you download the sample and examine the template Open XML document, you'll see that it contains a content control that surrounds each table and that content controls are inserted in each cell in the bottom row of each table. The tag for each content control in the table cells specifies the name of a column in the SharePoint lists. For convenience, I've also set the title of each content control to the same value as the tag. Content controls display their title when the insertion point is inside the control.

When you write the code for a SharePoint feature that generates an Open XML document, the code should first query the document for these content controls. The query returns an XML tree that describes the structure of the content controls, along with the tag for each. If you run this code on the sample document, it produces the following XML:

<ContentControls>

  <Table Name="Team Members">

    <Field Name="TeamMemberName" />

    <Field Name="Role" />

  </Table>

  <Table Name="Item List">

    <Field Name="ItemName" />

    <Field Name="Description" />

    <Field Name="EstimatedHours" />

    <Field Name="AssignedTo" />

  </Table>

</ContentControls>

This XML document shows which SharePoint lists our code needs to query. For each item in the list, you need to retrieve the values of the specified columns. The code to query the Open XML word-processing document, shown in Figure 7, is written as a LINQ to XML query that uses functional construction to form the returned XML.

To use functional construction, the code instantiates an XElement object using its constructor, passing a LINQ to XML query as an argument to the constructor. The LINQ to XML query uses axis methods to retrieve the appropriate elements in the body of the document and uses the Enumerable.Select extension method to form new XML from the results of the query. Functional construction takes a bit of study to understand, but as you can see, once you wrap your head around it, you can do an awful lot with just a little bit of code.

Figure 6 Open XML Markup for a Content Control

<w:p>

<w:r>

<w:t xml:space="preserve">Not in content control. </w:t>

</w:r>

<w:sdt>

<w:sdtPr>

<w:alias w:val="Test"/>

<w:tag w:val="Test"/>

<w:id w:val="5118254"/>

<w:placeholder>

<w:docPart w:val="DefaultPlaceholder_22675703"/>

</w:placeholder>

</w:sdtPr>

<w:sdtContent>

<w:r>

<w:t>This is text in content control.</w:t>

</w:r>

</w:sdtContent>

</w:sdt>

<w:r>

<w:t xml:space="preserve"> Not in content control.</w:t>

</w:r>

</w:p>

Preatomization of XName and XNamespace Objects

The code in Figure 7 uses an approach called "preatomization" of the LINQ to XML names. This is just a fancy way of saying that you write a static class (see Figure 8) that contains static fields that are initialized to the qualified names of the elements and attributes you are using.

Figure 7 Retrieving the Structure of the Content Controls in the Template Document

public static XElement GetContentControls(

WordprocessingDocument document)

{

XElement contentControls = new XElement("ContentControls",

document

.MainDocumentPart

.GetXDocument()

.Root

.Element(W.body)

.Elements(W.sdt)

.Select(tableContentControl =>

new XElement("Table",

new XAttribute("Name", (string)tableContentControl

.Element(W.sdtPr).Element(W.tag).Attribute(

W.val)),

tableContentControl

.Descendants(W.sdt)

.Select(fieldContentControl =>

new XElement("Field",

new XAttribute("Name",

(string)fieldContentControl

.Element(W.sdtPr)

.Element(W.tag)

.Attribute(W.val)

)

)

)

)

)

);

return contentControls;

}

There is a good reason to initialize XName and XNamespace objects in this fashion. LINQ to XML abstracts XML names and namespaces into two classes: System.Xml.Linq.XName and System.Xml.Linq.XNamespace, respectively. The semantics of these classes include the notion that if two XNames have the same qualified name (namespace + local name), they will be represented by the same object. This allows for fast comparison of XName objects. Instead of using a string comparison to select XElement objects of a given name, the code needs only to compare objects. When you initialize an XName object, LINQ to XML first looks in a cache to determine whether an XName object with the same namespace and name already exists. If one does, the object is initialized to the existing XName object from the cache. If one doesn't exist, LINQ to XML initializes a new one and adds it to the cache. As you might imagine, if this process is repeated over and over, it can result in performance issues. By initializing these objects in a static class, the work is done only once. In addition, by using this technique you reduce the possibility that an element or attribute name is misspelled in the body of the code. One other advantage is that by using this technique, you get support from IntelliSense, which makes writing Open XML programs using LINQ to XML easier.

Figure 8 A Static Class Containing Static Fields to Preatomize XName and XNamespace Objects

public static class W

{

public static XNamespace w =

"http://schemas.openxmlformats.org/wordprocessingml/2006/main";

public static XName body = w + "body";

public static XName sdt = w + "sdt";

public static XName sdtPr = w + "sdtPr";

public static XName tag = w + "tag";

public static XName val = w + "val";

public static XName sdtContent = w + "sdtContent";

public static XName tbl = w + "tbl";

public static XName tr = w + "tr";

public static XName tc = w + "tc";

public static XName p = w + "p";

public static XName r = w + "r";

public static XName t = w + "t";

public static XName rPr = w + "rPr";

public static XName highlight = w + "highlight";

public static XName pPr = w + "pPr";

public static XName color = w + "color";

public static XName sz = w + "sz";

public static XName szCs = w + "szCs";

}

The GetXDocument and PutXDocument Extension Methods

The example presented in this article also uses another little trick to ease programming and improve performance. The Open XML SDK has the ability to put annotations on parts in the document. This means that you can attach any .NET Framework object to an OpenXmlPart object and later retrieve it by specifying the type of the object that you attached.

We can define two extension methods, GetXDocument and PutXDocument, that use annotations to minimize deserialization of the XML from the Open XML part. When we call GetXDocument, it first looks to see whether an annotation of type XDocument exists on the OpenXmlPart. If the annotation exists, GetXDocument returns it. If the annotation doesn't exist, the method populates an XDocument from the part, annotates the part, and then returns the new XDocument.

The PutXDocument extension method also checks whether there is an annotation of type XDocument. If this annotation exists, PutXDocument writes the XDocument (presumably modified after the code calls GetXDocument) back to the OpenXMLPart. The GetXDocument and PutXDocument extension methods are shown in Figure 9. You can see the use of the GetXDocument extension method in the GetContentControls method listed earlier in Figure 7.

Figure 9 Extension Methods Use Open XML SDK Annotations to Minimize Deserialization of XML

public static class AssembleDocumentLocalExtensions

{

public static XDocument GetXDocument(this OpenXmlPart part)

{

XDocument xdoc = part.Annotation<XDocument>();

if (xdoc != null)

return xdoc;

using (Stream str = part.GetStream())

using (StreamReader streamReader = new StreamReader(str))

using (XmlReader xr = XmlReader.Create(streamReader))

xdoc = XDocument.Load(xr);

part.AddAnnotation(xdoc);

return xdoc;

}

public static void PutXDocument(this OpenXmlPart part)

{

XDocument xdoc = part.GetXDocument();

if (xdoc != null)

{

// Serialize the XDocument object back to the package.

using (XmlWriter xw =

XmlWriter.Create(part.GetStream

(FileMode.Create, FileAccess.Write)))

{

xdoc.Save(xw);

}

}

}

}

Replacing the Content Controls with Data

Now that we have a method that returns the structure of the content controls in the tables and cells, we need a method (SetContentControls) that creates an Open XML document with specific data (retrieved from the SharePoint lists) inserted in the tables. We can define this method to take an XML tree as an argument. The XML tree is shown in Figure 10, and Figure 11 shows the document that SetContentControls creates when it is passed the XML tree.

Figure 10 An XML Tree That Contains Data to Insert in the Word-Processing Document Tables

<ContentControls>

<Table Name="Team Members">

<Field Name="TeamMemberName" />

<Field Name="Role" />

<Row>

<Field Name="TeamMemberName" Value="Bob" />

<Field Name="Role" Value="Developer" />

</Row>

<Row>

<Field Name="TeamMemberName" Value="Susan" />

<Field Name="Role" Value="Program Manager" />

</Row>

<Row>

<Field Name="TeamMemberName" Value="Jack" />

<Field Name="Role" Value="Test" />

</Row>

</Table>

<Table Name="Item List">

<Field Name="ItemName" />

<Field Name="Description" />

<Field Name="EstimatedHours" />

<Field Name="AssignedTo" />

<Row>

<Field Name="ItemName" Value="Learn SharePoint 2010" />

<Field Name="Description" Value="This should be fun!" />

<Field Name="EstimatedHours" Value="80" />

<Field Name="AssignedTo" Value=”All” />

</Row>

<Row>

<Field Name="ItemName" Value=

"Finalize Import Module Specification" />

<Field Name="Description" Value="Make sure to handle all document

formats." />

<Field Name="EstimatedHours" Value="35" />

<Field Name="AssignedTo" Value=”Susan" />

</Row>

<Row>

<Field Name="ItemName" Value="Write Test Plan" />

<Field Name=”Description" Value=

"Include regression testing items." />

<Field Name="EstimatedHours" Value="20" />

<Field Name="AssignedTo" Value="Jack" />

</Row>

</Table>

</ContentControls>

Figure 11 The Generated Document

You can see that the single row that contained content controls has been replaced by multiple rows, each containing the data from the XML tree that was passed as an argument to the method. By using an XML tree to pass the data to the code that manipulates the Open XML markup, you achieve a nice separation of the code that uses the SharePoint object model and the Open XML code.

The code to assemble the new document honors any formatting you've applied to the table. For example, if you've configured the table to show different colors for alternating rows, or if you've set the background color of a column, the newly generated document reflects your formatting changes.

If you download and examine the ContentControlManager example, you can see that the code gets a copy of the row that contains content controls and saves it as a prototype row:

// Determine the element for the row that contains the content controls.

// This is the prototype for the rows that the code will generate from data.

XElement prototypeRow = tableContentControl

    .Descendants(W.sdt)

    .Ancestors(W.tr)

    .FirstOrDefault();

Then, for each item retrieved from the SharePoint list, the code clones the prototype row, alters the cloned row with the data from the SharePoint list, and adds it to a collection that is inserted into the document.

After creating the list of new rows, the code removes the prototype row from the list and inserts the collection of newly created rows, as shown here:

XElement tableElement = prototypeRow.Ancestors(W.tbl).First();

prototypeRow.Remove();

tableElement.Add(newRows);

Creating the SharePoint Feature

I used the February 2009 CTP release of the Visual Studio 2008 extensions for Windows SharePoint Services 3.0, v1.3 to build this example. I've built and run this example on both 32-bit and 64-bit versions of WSS. (Kirk Evans has some great webcasts that show how to use these extensions.)

The example contains the code to create the Web Part controls. The code is pretty self-explanatory if you are accustomed to building SharePoint Web Parts. When a user clicks the Generate Report button, the code calls the CreateReport method, which assembles the new Open XML word-processing document from the template document by using the data in the SharePoint lists as configured in the tags of the content controls.There are a few points to note about the code for the CreateReport method. Files in a document library in SharePoint are returned as byte arrays. You need to convert this byte array into a memory stream so that you can open and modify the document using the Open XML SDK. One of the MemoryStream constructors takes a byte array, and you might be tempted to use that constructor. However, the memory stream created with that constructor is a nonresizable memory stream, and the Open XML SDK requires that the memory stream be resizable. The solution is to create a MemoryStream with the default constructor and then write the byte array from SharePoint into the MemoryStream, as shown in Figure 12.

Figure 12 Writing a Byte Array from SharePoint to a MemoryStream

private ModifyDocumentResults CreateReport(SPFile file, Label message)

{

byte[] byteArray = file.OpenBinary();

using (MemoryStream mem = new MemoryStream())

{

mem.Write(byteArray, 0, (int)byteArray.Length);

try

{

using (WordprocessingDocument wordDoc =

WordprocessingDocument.Open(mem, true))

{

// Get the content control structure from the template

// document.

XElement contentControlStructure =

ContentControlManager.GetContentControls(wordDoc);

// Retrive data from SharePoint,

constructing the XML tree to

// pass to the ContentControlManager.SetContentControls

// method.

...

}

}

}

}

The remainder of the code is straightforward. It uses the SharePoint object model to retrieve document libraries and the contents of the libraries, retrieve lists and retrieve values of columns for each row in the list. It assembles the XML tree to pass to ContentControlManager.SetContentControls, and then it calls SetContentControls.

The code assembles the name of the generated report document as Report-yyyy-mm-dd. If the report already exists, the code appends a number to the report name to disambiguate the report from other reports that have already been generated. For instance, if Report-2009-08-01.docx already exists, the report is written to Report-2009-8-2 (1).docx.

Easy Customizations

You will probably want to customize this example to suit your own needs. One possible enhancement is to allow for a content control in the body of the template document that pulls boilerplate content from a specified document stored in SharePoint. You could write the code so that you could place the name of the document that contains the boilerplate text as text in the content control.

Also, this example hard-codes the names of the TemplateReports and the Reports document libraries. You could remove this constraint by specifying this information in a SharePoint list. The code would then know about the name of only this configuration list. The names of the TemplateReports and the Reports document libraries would be driven by data from your configuration list.

SharePoint is a powerful technology that makes it easy for people in organizations to collaborate. Open XML is a powerful emerging technology that is changing the way that we generate documents. Using the two technologies together enables you to build applications in which people can use documents to collaborate in new ways.

Eric White is a writer at Microsoft specializing in the Office Open XML file formats, Office and SharePoint. Before joining Microsoft in 2005, he worked as a developer for a number of years and then started PowerVista Software, a company that developed and sold a cross-platform grid widget. He has written books on custom control and GDI+ development. Read his blog at blogs.msdn.com/ericwhite.

SharePoint und Open XML

Generieren von Dokumenten aus SharePoint mit Open XML-Inhaltssteuerelementen

Eric White

Downloaden des Codebeispiels

Es ist häufig der Fall, dass ein Abteilungsleiter regelmäßig einen ordentlich formatierten Statusbericht an den Geschäftsführer oder ein Teamleiter einen wöchentlichen Statusbericht an eine Reihe von interessierten Parteien senden muss. Für eine Zusammenarbeit mit anderen Personen in ihren Organisationen können der Manager und der Teamleiter Statusinformationen in SharePoint-Listen verwalten. Die Frage für Entwickler ist, wie die Informationen in die Listen eines Dokuments, z. B. einen Statusbericht, aufgenommen werden sollen.

Open XML, das Standarddateiformat für Office 2007, ist ein ISO-Standard (in IS29500 ausführlich beschrieben). Open XML-Dateien sind im Grunde ZIP-Dateien, die XML enthalten. Es ist sehr einfach, Open XML-Dokumente programmgesteuert zu generieren oder zu ändern. Sie benötigen lediglich eine Bibliothek, um eine ZIP-Datei und eine XML-API zu öffnen. Mit den Programmierbarkeitsfeatures von Open XML und SharePoint können Sie ein kleines Dokumentgenerierungssystem zusammenstellen, das die Vorteile von Open XML-Inhaltssteuerelementen nutzt und Manager und Teamleiter verantwortlich für Ihre Berichte macht. In diesem Artikel werde ich einige Anleitungen und Beispielcode für das Erstellen eines Dokumentgenerierungssystems vorstellen, das SharePoint-Listen verwendet, um Tabellen in einem Open XML-Textverarbeitungsdokument mit Daten zu füllen.

Übersicht über das Beispiel

Das Beispiel in diesem Artikel ist ein kleines SharePoint-Webpart, das ein Open XML-Textverarbeitungsdokument anhand der Daten generiert, die in SharePoint-Listen enthalten sind. Ich habe zwei benutzerdefinierte SharePoint-Listen erstellt, die in Abbildung 1 dargestellt werden und die Daten enthalten, die wir in die Tabellen einfügen möchten.

Abbildung 1 Zwei benutzerdefinierte SharePoint-Listen

Ich habe auch ein Open XML-Textverarbeitungsdokument erstellt, das Inhaltssteuerelemente zum Definieren der Listen und Spalten enthält, die die Quelle der Daten für das generierte Dokument darstellen. Die Steuerelemente sind in Abbildung 2 dargestellt.

Abbildung 2 Das Open XML-Vorlagendokument, das Inhaltssteuerelemente enthält

Schließlich erstellte ich ein Webpart, das die Liste mit Vorlagendokumenten aus einer bestimmten Dokumentbibliothek abruft und die Liste den Benutzern vorstellt. Ein Benutzer wählt ein Element in der Liste und klickt dann auf die Schaltfläche „Bericht generieren“. Das Webpart erstellt ein Open XML-Textverarbeitungsdokument, platziert es in die Berichtsdokument-Bibliothek und leitet den Benutzer zu dieser Bibliothek, sodass er den Bericht öffnen kann. Das Webpart wird in Abbildung 3 angezeigt, und das generierte Dokument wird in Abbildung 4 angezeigt.

Abbildung 3 Ein SharePoint-Webpart, das den Benutzern die Auswahl eines Vorlagendokuments ermöglicht

Open XML-Inhaltssteuerelemente

Bevor ich die SharePoint-Lösung beschreibe, stelle ich die Grundlagen der Open XML-Inhaltssteuerelemente vor. Die Open XML-Inhaltssteuerelemente bieten in Textverarbeitungsdokumenten die Möglichkeit, Inhalt abzugrenzen und dem Inhalt Metadaten zuzuordnen. Für die Verwendung von Inhaltssteuerelementen müssen Sie die Registerkarte „Entwicklertools“ in Microsoft Office Word 2007 aktivieren. (Klicken Sie im Office-Menü auf Word-Optionen. Wählen Sie dann in der Multifunktionsleiste im Dialogfeld Word-Optionen die Registerkarte Entwicklertools.)

Um ein Inhaltssteuerelement einzufügen, markieren Sie Text, und klicken Sie dann im Bereich „Steuerelemente“ der Registerkarte „Entwicklertools“ auf die Schaltfläche, die ein Inhaltssteuerelement mit reinem Text erstellt, wie in Abbildung 5 dargestellt.

Abbildung 4 Ein Open XML-Textverarbeitungsdokument mit dem generierten Bericht

Abbildung 5 Verwenden Sie diese Schaltfläche zum Erstellen eines Nur-Text-Inhaltssteuerelements

Sie können Eigenschaften für ein Inhaltssteuerelement festlegen, um ihm einen Titel und ein Tag zuzuweisen. Klicken Sie in das Inhaltssteuerelement, und klicken Sie dann im Bereich „Steuerelemente“ auf der Registerkarte „Entwicklertools“ auf „Eigenschaften“. Es wird ein Dialogfeld angezeigt, das Sie verwenden können, um den Titel und das Tag festzulegen.

Inhaltssteuerelemente verwenden das w:sdt-Element im Open XML-Markup, das in Abbildung 6 dargestellt wird. Der Inhalt des Inhaltssteuerelements wird im w:sdtContent-Element definiert. In der Abbildung sehen Sie auch den Titel des Inhaltssteuerelements im w:alias-Element sowie das Inhaltssteuerelement-Tag im w:tag-Element.

Programmierung für Open XML unter Verwendung von .NET Framework

Sie können eine Vielzahl von Ansätzen für die Programmierung für Open XML ausführen, mit Microsoft .NET Framework:

Verwenden der Klassen im System.IO.Packaging
Verwenden Sie das Open XML-SDK zusammen mit einer beliebigen XML-Programmierungstechnologie in .NET, einschließlich XmlDocument, XmlParser oder LINQ to XML. Mein Favorit ist LINQ to XML.
Verwenden Sie das stark typisierte Objektmodell Open XML-SDK Version 2.0. Finden Sie eine Anzahl von Artikeln, die eine Einführung zum Programmieren mit diesem Objektmodell bieten.

Hier werde ich das Open XML-SDK (entweder Version 1.0 oder 2.0) mit LINQ to XML verwenden. Sie können das Open XML-SDK von go.microsoft.com/fwlink/?LinkId=127912 downloaden.

Es empfiehlt sich, einige Open XML-Funktionen um Inhaltssteuerelemente in einer ContentControlManager-Klasse zu kapseln. Wenn Sie das Problem auf diese Weise angehen, können Sie die Open XML-Funktionalität in eine einfache Konsolenanwendung entwickeln. Nachdem Sie die Open XML-Funktionalität codiert und gedebuggt haben, können Sie sie in Ihr SharePoint-Feature mit minimalem Aufwand integrieren. Es ist ziemlich zeitaufwändig, den Overhead der Bereitstellung des SharePoint-Features beim Debuggen von Open XML-Code zu übernehmen.

In unserem Beispiel der SharePoint-Dokumentgenerierung möchten wir Code schreiben, der ein Vorlagendokument aus einer bestimmten Dokumentbibliothek abruft, die Inhaltssteuerelemente des Dokuments abruft und die Metadaten in den einzelnen Inhaltssteuerelementen verwendet, um das Dokument mit Daten aus der entsprechenden SharePoint-Liste zu füllen.

Wenn Sie das Beispiel herunterladen und das Open XML-Dokument überprüfen, sehen Sie, dass es ein Inhaltssteuerelement enthält, das jede Tabelle umgibt, und dass Inhaltssteuerelemente in jeder Zelle in der unteren Zeile jeder Tabelle eingefügt werden. Das Tag für jedes Inhaltssteuerelement in den Tabellenzellen gibt den Namen einer Spalte in den SharePoint-Listen an. Der Einfachheit halber habe ich auch den Titel jedes Inhaltssteuerelement auf denselben Wert wie das Tag festgelegt. Die Inhaltssteuerelemente zeigen ihren Titel an, wenn sich die Einfügemarke innerhalb des Inhaltssteuerelementes befindet.

Wenn Sie den Code für ein SharePoint-Feature schreiben, der ein Open XML-Dokument generiert, sollte der Code zunächst das Dokument für diese Inhaltssteuerelemente abfragen. Die Abfrage gibt eine XML-Struktur zurück, die die Struktur der Inhaltssteuerelemente zusammen mit dem Tag für jedes Steuerelement beschreibt. Wenn Sie diesen Code für das Beispieldokument ausführen, wird die folgende XML erstellt:

<ContentControls>

  <Table Name="Team Members">

    <Field Name="TeamMemberName" />

    <Field Name="Role" />

  </Table>

  <Table Name="Item List">

    <Field Name="ItemName" />

    <Field Name="Description" />

    <Field Name="EstimatedHours" />

    <Field Name="AssignedTo" />

  </Table>

</ContentControls>

Dieses XML-Dokument zeigt, welche SharePoint-Listen unser Code abfragen soll. Für jedes Element in der Liste müssen Sie die Werte der angegebenen Spalten abrufen. Der Code zum Abfragen des Open XML-Textverarbeitungsdokuments, dargestellt in Abbildung 7 wird wie eine LINQ to XML-Abfrage geschrieben, das eine funktionale Erstellung zum Bilden der zurückgegebenen XML verwendet.

Um eine funktionale Erstellung zu verwenden, instanziiert der Code ein XElement-Objekt mit seinem Konstruktor, wobei eine LINQ to XML-Abfrage als Argument an den Konstruktor übergeben wird. Die LINQ to XML-Abfrage verwendet Achsenmethoden, um die entsprechenden Elemente im Textkörper des Dokuments abzurufen, und die Enumerable.Select-Erweiterungsmethode, um neue XML aus den Ergebnissen der Abfrage zu bilden. Die funktionale Erstellung muss ein wenig studiert werden, um sie zu verstehen, aber wie Sie sehen können, nachdem Sie sich erst einmal tiefer damit beschäftigt haben, können Sie sehr viel mit nur wenig Code machen.

Abbildung 6 Open XML-Markup für ein Inhaltssteuerelement

<w:p>

<w:r>

<w:t xml:space="preserve">Not in content control. </w:t>

</w:r>

<w:sdt>

<w:sdtPr>

<w:alias w:val="Test"/>

<w:tag w:val="Test"/>

<w:id w:val="5118254"/>

<w:placeholder>

<w:docPart w:val="DefaultPlaceholder_22675703"/>

</w:placeholder>

</w:sdtPr>

<w:sdtContent>

<w:r>

<w:t>This is text in content control.</w:t>

</w:r>

</w:sdtContent>

</w:sdt>

<w:r>

<w:t xml:space="preserve"> Not in content control.</w:t>

</w:r>

</w:p>

Preatomization (Vorab-Atomisierung) der Xname- und XNamespace-Objekte

Der Code in Abbildung 7 verwendet ein Verfahren namens "Preatomization" der LINQ to XML-Namen. Dies ist eine ausgefallene Möglichkeit, eine statische Klasse zu schreiben (siehe Abbildung 8), die statische Felder enthält, die für die verwendeten gekennzeichneten Namen der Elemente und Attribute initialisiert werden.

Abbildung 7 Abrufen der Struktur der Inhaltssteuerelemente im Vorlagendokument

public static XElement GetContentControls(

WordprocessingDocument document)

{

XElement contentControls = new XElement("ContentControls",

document

.MainDocumentPart

.GetXDocument()

.Root

.Element(W.body)

.Elements(W.sdt)

.Select(tableContentControl =>

new XElement("Table",

new XAttribute("Name", (string)tableContentControl

.Element(W.sdtPr).Element(W.tag).Attribute(

W.val)),

tableContentControl

.Descendants(W.sdt)

.Select(fieldContentControl =>

new XElement("Field",

new XAttribute("Name",

(string)fieldContentControl

.Element(W.sdtPr)

.Element(W.tag)

.Attribute(W.val)

)

)

)

)

)

);

return contentControls;

}

Es gibt gute Gründe, XName- und XNamespace-Objekte auf diese Weise zu initialisieren. LINQ to XML abstrahiert die XML-Namen und -Namespaces in zwei Klassen: System.Xml.Linq.XName bzw. System.Xml.Linq.XNamespace.. Die Semantik dieser Klassen enthält die Vorstellung, dass zwei XNames den gleichen qualifizierten Namen (Namespace + lokaler Name) haben, die durch das gleiche Objekt dargestellt werden. Dies ermöglicht einen schnellen Vergleich der XName-Objekte. Anstatt mithilfe eines Zeichenfolgenvergleichs XElement-Objekte mit einem bestimmten Namen auszuwählen, muss der Code nur Objekte vergleichen. Wenn Sie ein XName-Objekt initialisieren, sucht LINQ to XML zuerst in einem Cache, um zu bestimmen, ob bereits ein XName-Objekt mit dem gleichen Namespace und Namen vorhanden ist. Ist dies der Fall, wird das Objekt für das bereits vorhandene XName-Objekt aus dem Cache initialisiert. Andernfalls wird LINQ to XML für eine neue initialisiert und dem Cache hinzugefügt. Wie Sie sich vorstellen können, wenn dieser Prozess immer wieder wiederholt wird, kann es zu Leistungsproblemen kommen. Indem Sie diese Objekte in einer statischen Klasse initialisieren, erfolgt die Arbeit nur einmal. Mithilfe dieser Technik verringern Sie zusätzlich die Möglichkeit, dass ein Element- oder Attributname im Hauptteil des Codes falsch geschrieben wird. Ein anderer Vorteil ist, dass Sie mithilfe dieser Technik Unterstützung von IntelliSense erhalten, womit das Schreiben von Open XML-Programmen mithilfe von LINQ to XML einfacher wird.

Abbildung 8 Eine statische Klasse enthält statische Felder für die Vorab-Atomisierung von Xname- und XNamespace-Objekten

public static class W

{

public static XNamespace w =

"http://schemas.openxmlformats.org/wordprocessingml/2006/main";

public static XName body = w + "body";

public static XName sdt = w + "sdt";

public static XName sdtPr = w + "sdtPr";

public static XName tag = w + "tag";

public static XName val = w + "val";

public static XName sdtContent = w + "sdtContent";

public static XName tbl = w + "tbl";

public static XName tr = w + "tr";

public static XName tc = w + "tc";

public static XName p = w + "p";

public static XName r = w + "r";

public static XName t = w + "t";

public static XName rPr = w + "rPr";

public static XName highlight = w + "highlight";

public static XName pPr = w + "pPr";

public static XName color = w + "color";

public static XName sz = w + "sz";

public static XName szCs = w + "szCs";

}

Die GetXDocument- und PutXDocument-Erweiterungsmethoden

Im Beispiel in diesem Artikel wird auch ein anderer kleiner Trick für eine einfachere Programmierung und Verbesserung der Leistung verwendet. Open XML SDK bietet die Möglichkeit, Anmerkungen in Teilen des Dokuments einzufügen. Dadurch können Sie einem OpenXmlPart-Objekt ein beliebiges .NET Framework-Objekt zuordnen und später durch Angabe des Objekttyps, den Sie zugeordnet haben, abrufen.

Wir können zwei Erweiterungsmethoden, GetXDocument und PutXDocument, definieren, die Anmerkungen für die Deserialisierung von XML aus dem Open XML-Teil zu minimieren. Wenn wir GetXDocument aufrufen, sucht es zuerst, ob eine Anmerkung des Typs XDocument im OpenXmlPart vorhanden ist. Wenn die Anmerkung vorhanden ist, gibt GetXDocument sie zurück. Wenn die Anmerkung vorhanden ist, füllt die Methode ein XDocument aus dem Teil, versieht den Teil mit Anmerkungen und gibt dann das neue XDocument zurück.

Die PutXDocument-Erweiterungsmethode überprüft auch, ob eine Anmerkung des Typs XDocument vorhanden ist. Wenn diese Anmerkung vorhanden ist, schreibt PutXDocument das XDocument (vermutlich geändert, nachdem der Code GetXDocument aufgerufen hat) zurück in die OpenXMLPart. Die GetXDocument- und PutXDocument-Erweiterungsmethoden sind in Abbildung 9 dargestellt. Sie können die Verwendung der GetXDocument-Erweiterungsmethode GetContentControls-Methode in der oben aufgeführten Abbildung 7 anzeigen.

Abbildung 9 Erweiterungsmethoden verwenden Open XML-SDK-Anmerkungen zum Minimieren der Deserialisierung von XML-

public static class AssembleDocumentLocalExtensions

{

public static XDocument GetXDocument(this OpenXmlPart part)

{

XDocument xdoc = part.Annotation<XDocument>();

if (xdoc != null)

return xdoc;

using (Stream str = part.GetStream())

using (StreamReader streamReader = new StreamReader(str))

using (XmlReader xr = XmlReader.Create(streamReader))

xdoc = XDocument.Load(xr);

part.AddAnnotation(xdoc);

return xdoc;

}

public static void PutXDocument(this OpenXmlPart part)

{

XDocument xdoc = part.GetXDocument();

if (xdoc != null)

{

// Serialize the XDocument object back to the package.

using (XmlWriter xw =

XmlWriter.Create(part.GetStream

(FileMode.Create, FileAccess.Write)))

{

xdoc.Save(xw);

}

}

}

}

Ersetzen der Inhaltssteuerelemente durch Daten

Nachdem wir nun über eine Methode verfügen, die die Struktur der Inhaltssteuerelemente in den Tabellen und Zellen zurückgibt, benötigen wir eine Methode (SetContentControls), die ein Open XML-Dokument mit bestimmten Daten erstellt (aus den SharePoint-Listen abgerufen), die in den Tabellen eingefügt sind. Definieren wir diese Methode, um eine XML-Struktur als Argument zu verwenden. Die XML-Struktur wird in Abbildung 10 dargestellt, und Abbildung 11 zeigt das Dokument, das von SetContentControls erstellt wird, wenn ihm die XML-Struktur übergeben wird.

Abbildung 10 Eine XML-Struktur mit Daten zum Einfügen in die Tabellen des Textverarbeitungsdokuments

<ContentControls>

<Table Name="Team Members">

<Field Name="TeamMemberName" />

<Field Name="Role" />

<Row>

<Field Name="TeamMemberName" Value="Bob" />

<Field Name="Role" Value="Developer" />

</Row>

<Row>

<Field Name="TeamMemberName" Value="Susan" />

<Field Name="Role" Value="Program Manager" />

</Row>

<Row>

<Field Name="TeamMemberName" Value="Jack" />

<Field Name="Role" Value="Test" />

</Row>

</Table>

<Table Name="Item List">

<Field Name="ItemName" />

<Field Name="Description" />

<Field Name="EstimatedHours" />

<Field Name="AssignedTo" />

<Row>

<Field Name="ItemName" Value="Learn SharePoint 2010" />

<Field Name="Description" Value="This should be fun!" />

<Field Name="EstimatedHours" Value="80" />

<Field Name="AssignedTo" Value=”All” />

</Row>

<Row>

<Field Name="ItemName" Value=

"Finalize Import Module Specification" />

<Field Name="Description" Value="Make sure to handle all document

formats." />

<Field Name="EstimatedHours" Value="35" />

<Field Name="AssignedTo" Value=”Susan" />

</Row>

<Row>

<Field Name="ItemName" Value="Write Test Plan" />

<Field Name=”Description" Value=

"Include regression testing items." />

<Field Name="EstimatedHours" Value="20" />

<Field Name="AssignedTo" Value="Jack" />

</Row>

</Table>

</ContentControls>

Abbildung 11 Das generierte Dokument

Sie können sehen, dass die einzelne Zeile, die Inhaltssteuerelemente enthielt, durch mehrere Zeilen ersetzt wurde, von denen jede die Daten aus der XML-Struktur enthält, die als Argument an die Methode übergeben wurde. Wenn Sie eine XML-Struktur verwenden, um die Daten an den Code zu übergeben, der das Open XML-Markup bearbeitet, erreichen Sie eine gute Trennung des Codes, der das SharePoint-Objektmodell und den Open XML-Code verwendet.

Der Code für die Zusammenstellung des neuen Dokuments berücksichtigt alle in der Tabelle angewendeten Formatierungen. Wenn Sie die Tabelle für die Ansicht unterschiedlicher Farben für abwechselnde Zeilen konfiguriert haben oder wenn Sie die Hintergrundfarbe einer Spalte festgelegt haben, zeigt das neu erstellte Dokument die Formatierungsänderungen an.

Wenn Sie das ContentControlManager-Beispiel downloaden und untersuchen, sehen Sie, dass der Code eine Kopie der Zeile abruft, die Inhaltssteuerelemente enthält, und speichert es als Prototyp-Zeile:

// Determine the element for the row that contains the content controls.

// This is the prototype for the rows that the code will generate from data.

XElement prototypeRow = tableContentControl

    .Descendants(W.sdt)

    .Ancestors(W.tr)

    .FirstOrDefault();

Für jedes aus der SharePoint-Liste abgerufene Element klont der Code die Prototyp-Zeile, ändert die geklonte Zeile mit den Daten aus der SharePoint-Liste und fügt sie einer Auflistung hinzu, die in das Dokument eingefügt wird.

Nachdem Sie die Liste der neuen Zeilen erstellt haben, entfernt der Code die Prototypzeile aus der Liste und fügt die Auflistung der neu erstellten Zeilen ein, wie hier dargestellt:

XElement tableElement = prototypeRow.Ancestors(W.tbl).First();

prototypeRow.Remove();

tableElement.Add(newRows);

Erstellen des SharePoint-Features

Ich verwendete die CTP-Version von Februar 2009 der Visual Studio 2008-Erweiterungen für Windows SharePoint Services 3.0, Version 1.3, um dieses Beispiel zu erstellen. Ich habe dieses Beispiel sowohl für 32-Bit- als auch für 64-Bit-Versionen von WSS erstellt und ausgeführt. (Kirk Evans hat einige hervorragende Webcasts, die die Verwendung dieser Erweiterungen zeigen.)

Das Beispiel enthält den Code zum Erstellen der Webparts-Steuerelemente. Der Code ist relativ selbsterklärend, wenn Sie an das Erstellen von SharePoint-Webparts gewöhnt sind. Klickt ein Benutzer auf die Schaltfläche „Bericht erstellen“, ruft der Code die CreateReport-Methode auf, die das neue Open XML-Textverarbeitungsprogrammen aus dem Vorlagendokument zusammenstellt, mithilfe der Daten in den SharePoint-Listen, wie in den Tags der Inhaltssteuerelemente konfiguriert. Einige Punkte sind zu beachten beim Code für die CreateReport-Methode. Die Dateien in einer Dokument Bibliothek in SharePoint werden als Bytearrays zurückgegeben. Sie müssen dieses Bytearray in einen Arbeitsspeicherstream konvertieren, sodass Sie das Dokument mit dem Open XML-SDK öffnen und ändern können. Eine der MemoryStream-Konstruktoren akzeptiert ein Bytearray, und Sie möchten eventuell diesen Konstruktor verwenden. Jedoch ist der mit diesem Konstruktor erstellte Arbeitsspeicherstream ein in der Größe nicht veränderbarer Arbeitsspeicherstream, und das Open XML-SDK erfordert, dass der Arbeitsspeicherstream in der Größe veränderbar ist. Die Lösung ist ein MemoryStream mit dem Standardkonstruktor zu erstellen und das Bytearray aus SharePoint in den MemoryStream zu schreiben, wie in Abbildung 12 dargestellt.

Abbildung 12 Schreiben eines Bytearrays aus SharePoint in einen MemoryStream

private ModifyDocumentResults CreateReport(SPFile file, Label message)

{

byte[] byteArray = file.OpenBinary();

using (MemoryStream mem = new MemoryStream())

{

mem.Write(byteArray, 0, (int)byteArray.Length);

try

{

using (WordprocessingDocument wordDoc =

WordprocessingDocument.Open(mem, true))

{

// Get the content control structure from the template

// document.

XElement contentControlStructure =

ContentControlManager.GetContentControls(wordDoc);

// Retrive data from SharePoint,

constructing the XML tree to

// pass to the ContentControlManager.SetContentControls

// method.

...

}

}

}

}

Der Rest des Codes ist einfach. Es wird das SharePoint-Objektmodell zum Abrufen von Dokumentbibliotheken und des Inhalts der Bibliotheken, der Listen und von Werten der Spalten für jede Zeile in der Liste verwendet. Es stellt die XML-Struktur zusammen, die an die ContentControlManager.SetContentControls übergeben werden soll, und ruft dann SetContentControls auf.

Der Code assembliert den Namen des generierten Berichtdokuments als Bericht-jjjj-mm-tt. Wenn der Bericht bereits vorhanden ist, fügt der Code eine Zahl an den Berichtsnamen an, um den Bericht von anderen Berichten zu unterscheiden, die bereits erstellt wurden. Falls beispielsweise Bericht-2009-08-01.docx vorhanden ist, wird der Bericht in den Bericht-2009-8-2 (1).docx geschrieben.

Einfache Anpassung

Sie möchten wahrscheinlich dieses Beispiel an Ihre eigenen Bedürfnisse anpassen. Eine mögliche Verbesserung besteht darin, ein Inhaltssteuerelement im Hauptteil des Vorlagendokuments zu ermöglichen, das häufig verwendeten Inhalt aus einem angegebenen Dokument, das in SharePoint gespeichert ist, abruft. Sie können den Code so schreiben, dass Sie den Namen des Dokuments platzieren können, der den vorformulierten Text in das Inhaltssteuerelement als Text enthält.

Auch in diesem Beispiel werden die Namen der TemplateReports- und die Reports-Dokumentbibliotheken hartcodiert. Sie könnten diese Einschränkung entfernen, indem Sie diese Informationen in einer SharePoint-Liste angeben. Der Code würde dann den Namen dieser Konfigurationsliste kennen. Die Namen der TemplateReports- und der Reports-Dokumentbibliotheken würde von Daten aus der Konfigurationsliste gesteuert werden.

SharePoint ist eine leistungsstarke Technologie, die Personen in Organisationen die Zusammenarbeit erleichtert. Open XML ist eine leistungsfähige Technologie, mit der die Art und Weise geändert wird, wie wir Dokumente generieren. Die Verwendung beider Technologien zusammen ermöglicht die Erstellung von Anwendungen, in denen Personen Dokumente verwenden können, um auf neue Weise zusammenzuarbeiten.

Eric White ist Autor bei Microsoft, der sich auf Office Open XML-Dateiformate, Office und SharePoint spezialisiert hat. Bevor er 2005 zu Microsoft kam, arbeitete er für einige Jahre als Entwickler und anschließend gründete er dann PowerVista Software, ein Unternehmen, das eine plattformübergreifende Raster Widget entwickelte und verkaufte. Er hat Bücher über benutzerdefinierte Steuerelemente und GDI+-Entwicklung geschrieben. Lesen Sie seinen Blog unter blogs.msdn.com/ericwhite.

Current Issue

Browse All MSDN Magazines

Tip: Click the printer button in your browser toolbar to get the printer friendly version of this article.