Version

WordprocessingMLWriter Class

Represents a writer that provides a fast, non-cached, forward-only way of generating streams or files containing XML data that conforms to the WordprocessingML OpenXml specification.
Syntax
'Declaration
 
Public Class WordprocessingMLWriter 
   Inherits WordDocumentWriter
public class WordprocessingMLWriter : WordDocumentWriter 
Remarks

The WordprocessingMLWriter class is a concrete implementation of the WordDocumentWriter class which produces content that is recognizable by WordprocessingML OpenXml consumers such as Microsoft Word 2007.

The developer communicates with the WordDocumentWriter in a "forward-only" manner; as soon as a content creation method is called, that content is irreversibly written to the target document. While this method is generally considered to be more complicated, it offers the benefit of a greatly reduced memory footprint over an object-driven approach.

A new instance of this class can be created using the Create method.

To begin a new WordprocessingML document, the developer calls the StartDocument method. This method starts the <document> and <body> elements for the document. After execution returns from the method, these elements are left open, so that content can be added. The elements are not closed until the developer calls the EndDocument method, or until the WordDocumentWriter instance is disposed of.

After the StartDocument method is called, blocks of content can be added via (for example) the StartParagraph method. After adding a paragraph, the developer will typically populate it with content using methods like AddTextRun and AddHyperlink. These methods are executed as atomic operations, i.e., all content required to represent the content run is added to the document stream before execution returns from the method. After all content has been added to the paragraph, the developer calls the EndParagraph method to close the paragraph element.

Attempting to add content to the document when the writer is not in the required state for the operation causes a WordDocumentWriterException to be thrown. For example, calling the AddTextRun method when the StartParagraph method had not previously been called to open a paragraph is not valid (since a text run must belong to a paragraph) and will cause an exception to be thrown. These exceptions can be handled for debugging purposes during the early phases of application development, but there is generally no way for the developer to recover gracefully from these exceptions, and they should be interpreted as in indication that there is a problem with the client code.

After all content blocks have been added, the developer calls the EndDocument method to close the <document> and <body> elements.

Page size, margins, and orientation can be set for the entire document via the FinalSectionProperties property, and for a range of previously written paragraphs and tables via the DefineSection method.

The content stream is closed when the WordDocumentWriter is disposed of, and the resulting WordprocessingML file is created.

The developer can specify the unit of measure to be used when interpreting properties which represent graphical measurements using the Unit property. The objects returned from the CreateFont, CreateParagraphProperties, and CreateAnchoredPicture methods maintain a reference to this class, and use the value of the Unit property to determine the unit of measure in which to express certain property values. For example, if the developer assigns a value of 'Inch' to the Unit property, then obtains a Font using the CreateFont method, the get method of the Size property will return the value expressed in inches, and the set method will assume the values assigned to it to be expressed in inches. This association is maintained for the lifetime of the object, so that if the developer changes the value of the Unit property, the new unit of measure is automatically used the next time the property is accessed.

Requirements

Target Platforms: Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

See Also