Merging Documents with RESTful Web API's

ASP.NET Web API is a framework that makes it easy to build HTTP services that reach a broad range of clients, including browsers and mobile devices. ASP.NET Web API is an ideal platform for building RESTful applications on the .NET Framework.

Source: Microsoft - Learn About ASP.NET Web API (http://www.asp.net/web-api)

Service based architectures and centralized systems to generate documents help to build clean and structured software concepts. Creating documents by merging templates with data is a typical task for an HTTP service.

This tutorial shows how to create a very simple Web API that expects a template in the TX Text Control InternalUnicodeFormat and data bundled in a JSON (JavaScript Object Notation) object.

Before we are walking through the steps that are required to create an ASP.NET Web API project with Visual Studio, the JSON data objects are explained.

The MailMergeRequestObject Helper Class

These helper classes simply keep the data that is encrypted as an JSON object and used for the data transportation. The class MailMergeRequestObject consists of the template in the internal TX Text Control format and data as an JSON object. The ResponseResults object, that comes back from the HTTP service, holds the resulting document as a byte array in the internal TX Text Control format.

The data is expected as a structured JSON object in the following form:

Creating the Web API Project

1. Open Visual Studio (in this tutorial, Visual Studio 2015 is used) and create a new ASP.NET Web Application. Select Web API as the project template and confirm with OK.

   

2. Select the project in the Solution Explorer and choose Add Class... from the Project main menu. Name the class MailMergeRequestObject and add the following two helper classes to the newly created file:

   	public class MailMergeRequestObject
   	{
   	public string Data { get; set; }
   	public byte[] Template { get; set; }
   	public MailMergeRequestObject() { }
   	}
   	public class ResponseResults
   	{
   	public byte[] Document { get; set; }
   	public ResponseResults() { }
   	}

   view raw MailMergeRequestObject.cs hosted with ❤ by GitHub

3. Select the project in the Solution Explorer and choose Add Reference... from the Project main menu. Browse for the assemblies TXTextControl.Server, TXDocumentServer.dll and TXTextControl.dll, select them and confirm with OK.

   

4. In the Solution Explorer, right-click the Controllers folder and choose Controller... from the Add context menu. Select Web API 2 Controller - Empty and confirm with Add. Name the controller MergeController.

   

5. Open the newly created MergeController.cs file and replace the code with the following implementation:

   	/*-----------------------------------------------------------------
   	** Post method
   	** // POST api/merge?format=[PDF|PDFA|DOCX|DOC]
   	**---------------------------------------------------------------*/
   	public ResponseResults Post([FromBody]dynamic mailMergeRequestObject,
   	[FromUri]string format)
   	{
   	// create a new ResponseResults object that contains the
   	// resulting document as a byte[]
   	ResponseResults results = new ResponseResults();
   	// helper object of type 'MailMergeRequestObject' to extract the
   	// JSON data (template and data)
   	MailMergeRequestObject mmroJSONResult =
   	(MailMergeRequestObject)JsonConvert.DeserializeObject(
   	Convert.ToString(mailMergeRequestObject),
   	typeof(MailMergeRequestObject));
   	// create a new ServerTextControl
   	using (TXTextControl.ServerTextControl tx =
   	new TXTextControl.ServerTextControl())
   	{
   	tx.Create();
   	// create a new MailMerge instance
   	using (TXTextControl.DocumentServer.MailMerge mm =
   	new TXTextControl.DocumentServer.MailMerge())
   	{
   	mm.TextComponent = tx;
   	// load the template from the helper object
   	mm.LoadTemplateFromMemory(mmroJSONResult.Template,
   	TXTextControl.DocumentServer.FileFormat.InternalUnicodeFormat);
   	// create a new DataSet and the given XML data into it
   	DataSet ds = new DataSet();
   	XmlDocument doc =
   	JsonConvert.DeserializeXmlNode(mmroJSONResult.Data);
   	XmlNodeReader reader = new XmlNodeReader(doc);
   	ds.ReadXml(reader, XmlReadMode.Auto);
   	// merge the template with the DataSet
   	mm.Merge(ds.Tables[0]);
   	byte[] data;
   	BinaryStreamType streamType = BinaryStreamType.AdobePDF;
   	// define the export format based on the given Uri parameter
   	switch (format.ToUpper())
   	{
   	case "PDFA":
   	streamType = BinaryStreamType.AdobePDFA; break;
   	case "DOCX":
   	streamType = BinaryStreamType.WordprocessingML; break;
   	case "DOC":
   	streamType = BinaryStreamType.MSWord; break;
   	}
   	// save the document and fill the 'ResponseResults' object
   	mm.SaveDocumentToMemory(out data, streamType, null);
   	results.Document = data;
   	}
   	}
   	// return the 'ResponseResults' object
   	return results;
   	}

   view raw MergeController.cs hosted with ❤ by GitHub

Calling the Web API

The above ASP.NET Web API can now be called on the following URL:

[...]/api/merge?format=PDF

The following demo project code shows how to read an XML data source and a template, package both into a JSON object in order to call the Web API using an HTTP Post request.

Download the sample from GitHub and test it on your own.