Choosing the right kind of a Data Source
In this article I’m going to highlight the importance of choosing the right kind of data sources when planning a document generation solution in a .NET project with Docentric Toolkit. While Docentric Toolkit is easy to start with, you might make a wrong turn at the beginning and choose to work with the kind of a data source that will not allow to squeeze maximum from it.
Docentric Toolkit offers two kinds of data sources to work with: .NET Objects and XML. Statistically, the majority of developers decide to use .NET Objects as data sources for Docentric Toolkit templates rather than XML. The reason for this is obvious: These data classes and the corresponding data access logic in most cases already exist in projects: in the form of Data Sets, DTOs, Entity Framework or any other ORM entities. So why not reusing these objects as data sources directly? Besides, these classes can immediately be also used for importing schemas for template data sources.
While using .NET Objects as data sources directly can be a perfectly good choice, it can sometimes lead to a non-optimal solution that will impede document/report development later when you will already have tens or even hundreds of different templates.
The fact is that while setting up a Docentric Toolkit POC (Proof Of Concept) is usually the quickest by using .NET Objects as data sources. But later you might realize that you could be better off if you chose XML instead. Why? Simply because working with XML data sources offer functionality that is not available for .NET objects. To show what I mean, let’s enumerate pros and cons for each data source kind.
NET Objects
PROS
- The easiest and quickest start for most data-centric applications
As said before, most .NET applications already expose data in the form of DTOs, business objects or entities which are consumed by a presentation or UI layer. In the same way these objects can be used to populate Docentric Toolkit template documents.
CONS
- No data shaping in templates available
Template placeholders and other tagging elements can only be data-bound to the properties and fields of the data source classes. There are no expressions or formulas available that would enable you to have placeholders with calculated values. If you will need to display values that are calculated, you will need to add calculated properties to data source classes. This is why it is highly recommended to create a separate layer of classes that act as “View Models”, instead of using business object/model classes directly. This is a best-practice approach that will be covered in another article. - No Preview
Currently there is no preview functionality available for templates with .NET Object data sources. When you want to test a template against data, you will have to leave MS Word and run your .NET application/project to generate a document from the template. This can be very cumbersome if your templates are large and you want to run a lot of tests during template design.
XML
PROS
- Hi flexibility
Full XPath is at your disposal when using XML data sources. When data-binding template placeholders and other tagging elements you can write XPath expressions. Compared to working with .NET Object data sources this can make a big difference if flexibility is needed. Docentric Toolkit’s XPath has even been extended with many additional functions that are not available by standard XPath.
- Preview available
Unlike for a .NET Object data source, you can specify test data XML for an XML data source in a template. By specifying preview data you will be able to use the Preview button which will generate a document from the template and the test XML. This can be a real advantage for more complex templates.
CONS
- Generation of XML
When considering XML as an option it is pretty obvious that, unless your application already generates data in the form of XML, you will need to convert your application’s DataSets, DTOs, or any other objects holding the data into XML. There is currently nothing out-of-the-box in Docentric Toolkit that you could use to convert your data objects to XML. You will need to create your own classes for conversion to XML. The good news is that such functionality is in most cases generic and must only be written once and then used for each report execution across whole project.
Conclusion
It is well worth considering whether XML would be a better option, before creating a myriad of different templates and the corresponding source code in the project.
If your project involves only several simple templates which will not be modified a lot through the application lifetime then you can do the shortcut and use your entity objects directly as the data sources for the templates. For any calculated value not available as a property or a field on a data source object you can use the technique involving named tagging elements and the ElementInitialize event handler.
Even if you have a lot of templates and these templates are complex, you can still use .NET Objects as data sources, but not directly. You will very quickly run into a situations with values that are not provided by data object. Instead, create another layer of View Model-like classes/objects and populate them from the data/entity/model objects. This approach involves more work but the solution will be more robust and you will be able to add later new properties more easily.
Another scenario involves flexibility. If you don’t know what data fields and information you will need to include on a template at the beginning, then you will need to add additional properties to your data source object for each new requirement from an end user. Even worse, if your end users are allowed to design templates themselves, then they will very quickly run into a situation where they require to display a value not directly available in the data source schema, but could be calculated from existing properties. And this is where XML data sources have advantage over .NET Object data sources.
About the Author
