A .NET Word Document Reporting Component




A .NET Word Document Reporting Component


By Steve C. Orr


So you want to create downloadable, dynamic Microsoft Word documents for the users of your Web site. You could use COM automation to have Word itself generate the documents for you. This isn't a bad choice for a Windows Forms application; however, there are many reasons why it's a bad idea for Web applications, including licensing issues, poor performance, and virtually no scalability.


For basic documents you could output plain HTML to your Web page and simply change the Response.ContentType to "application/ms-word", causing the document to open inside Word on the user's machine. However, this approach falls short when you want or need more advanced control over the document creation process, such as filling in templates, or using mail merge, lists, headers, and drawing objects.


Aspose.Word provides a good solution to all these problems.



Written years ago in unmanaged code, Word was designed to be run as a single-user desktop application. Its threading model does not gracefully support use as a server component. On the other hand, Aspose.Word is written entirely in C# and has no dependencies (other than the .NET Framework, of course). Word is not required on your server, because Aspose.Word itself acts as the document creation engine. This delivers all kinds of scalability and frees you from potentially daunting Microsoft licensing requirements. To view the generated documents, your users will either need Word installed on their computers or the Word file viewer, which can be downloaded free from Microsoft.


The speed of this product is generally snappy, although sometimes for no obvious reason documents appear to be generated noticeably faster than other times. According to Aspose, informal testing has demonstrated that a standard desktop PC can generate roughly 180,000 moderately complex five-page documents per hour. Now that's performance!


Flexible Solutions

One way to go about using the custom class library exposed by Aspose.Word is to ignore it. Instead, open Word and build an example of what you want your final document to look like. You can set up static text, colors, tables, fonts, images, etc. in advance. Wherever you want dynamic data to be inserted, insert a merge field. (To do this, select Field from the Insert dropdown menu in Word. Then choose MergeField from the list of field names and give the field a unique name so you can reference it from your code.) This standard Word file will act as your template, or as the Aspose documentation names it, a "designer." Then at run time you can use the Aspose.Word object model to merge the data with your designer to result in a snazzy looking document full of juicy data. If you prefer, you can skip the designer and generate every aspect of the document at run time. Or you can mix and match the techniques in virtually any way imaginable. Almost every available feature can be specified at design time or run time.


Figure 1 shows a simple VB.NET example that fills in a couple of fields in an existing Word template and outputs it to the browser. After instantiating the Aspose.Word object and pointing it to your template file, you then pass it an array of field names and an array of their associated values. The final statement saves the document to the output stream and opens it in the user's browser. You can optionally choose to open it in an independent instance of Word outside the Web browser, although my tests of this functionality caused the same standard download prompt to appear twice in a row before opening the document - not quite acceptable for a production system. You can also choose to output in text format, or if you've purchased the companion product, Aspose.PDF, you can choose to output to PDF just as easily by specifying SaveFormat.FormatAsposePdf.


' Instantiate and configure the Aspose.Word object.

Dim word As Word = New Word

Dim doc As Document = _

  word.Open(MapPath(".") + "\MyTest.doc")


' Fill the fields in the document with user data.

doc.MailMerge.Execute( _

   New String() {"FirstName", "LastName"}, _

   New Object() {"Steve", "Orr"})


' Send the document in Word format to the user's browser.

doc.Save("MyTest.doc", _

  SaveFormat.FormatDocument, _

  SaveType.OpenInBrowser, _


Figure 1: This code "fills in the blanks" of an existing Word document and allows it to be downloaded into the user's browser.


If you want a repeatable table of data, instead of (or in addition to) merely filling in a few disparate fields, you can output an entire formatted DataSet, DataTable, DataReader, or DataView with one line of code:




You can also designate repeatable merge mail regions that will be repeated for each record in a datasource. For example, a table row can be marked as a repeatable region to cause the table to grow dynamically to accommodate all the data. If you don't use mail merge regions you can cause the whole document to be repeated for each record, which might be handy for quick and simple mass mailings.


Intuitive Object Model

The object model of Aspose.Word is similar to the object model of Word itself, so you should feel right at home if you've done any Office automation with Word. Although you won't find every Word object, you'll find many of the most useful and familiar ones, such as Document, Section, Range, Bookmark, and FormField.


Once the Aspose.Word object library has been referenced from a new ASP.NET application in Visual Studio.NET, it only takes several lines of code to output a simple document from scratch. Import the Aspose.Word namespace and input the VB.NET code shown in Figure 2.


Dim word As Word = New Word

Dim doc As Document = word.Open(MapPath(".") + "\blank.doc")

Dim builder As DocumentBuilder = New DocumentBuilder(doc)


' Specify font formatting before adding text.

builder.Font.Size = 18

builder.Font.Bold = True

builder.Font.Name = "Garamond"

builder.Underline = Underline.Thick

builder.Font.Color = System.Drawing.Color.Green



' Specify different formatting for next section.

builder.Font.Bold = True

builder.Underline = Underline.Dotted

builder.Font.Color = System.Drawing.Color.DarkBlue



' Send the document in Word format to the client browser.

doc.Save("MyTest.doc", _

  SaveFormat.FormatDocument, _

  SaveType.OpenInWord, _


Figure 2: The object model of Aspose.Word is very similar to the object model of Word, so you should feel right at home if you've done any Office automation with Word.


The first two statements simply instantiate the Aspose.Word object, and creates a DocumentBuilder object, which will be used to craft the document from the ground up. The code then goes on to specify font settings, before outputting the first text. Then different font settings are set for the next section of text. Finally, the document is output to the client machine, which then opens in Word.


The DocumentBuilder is a new object not found in the Word object model. This intuitive object can be used to create paragraphs, lists, tables, and more. You can use it to insert images or move to specific sections of a document.


Free Stuff

After you download the free evaluation version of Aspose.Word and run the simple installation, one of the first things you're likely to notice is the sample code. No matter what kind of document you need to generate, you're likely to find similar code in their samples that can be modified for your own needs. This sample code is available in VB.NET and C#.


The API documentation is sufficient, with the most important functionality being covered the most thoroughly. Every object, method, and property is referenced in the help file, with example code included in C# and VB.NET. It would be nice if the help documentation was integrated with Visual Studio.NET's help system, but the link is easy enough to find on your Start menu. The local documentation is supplemented by online documentation, including a free forum full of common questions and answers. Aspose watches their forums closely for ideas to put in future versions of the product. This, combined with free upgrades, makes it a tempting value.


There are several editions of Aspose.Word available: Basic, Standard, Professional, Corporate, and Enterprise. Prices start at around $230 for one Basic license. Only the higher-end versions support such advanced functionality as headers and footers and image support. You could shell out thousands for some fancy report writer suite, but for many projects I suspect this product is a much better solution.



Web Site:

Price: Starting around $230 USD



Hide comments


  • Allowed HTML tags: <em> <strong> <blockquote> <br> <p>

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.