A template engine for the .NET platform which takes a DOCX file and applies a data object to generate reports, do mail merges, etc. All without introducing a dependency on MS Word.
Install the engine via NuGet, either in Visual Studio (right-click project, Manage NuGet Packages, search for docxtemplateengine) or via the package manager console using Install-Package DocXTemplateEngine.
In template.docx - use a field (Insert / Quick Parts / Field), Field type is MergeField and enter the field or property name in Field:
Brought to you by «Name»!
In code:
var templateEngine = new swxben.docxtemplateengine.DocXTemplateEngine();
templateEngine.Process(
source = "template.docx",
destination = "dest.docx",
data = new {
Name = "SWXBEN"
});
data can be just about any data type. Fields and properties are iterated, and if it can be cast to IDictionary<object, string> (such as a dynamic ExpandoObject) the dictionary entries are iterated.
dest.docx is created:
Brought to you by SWXBEN!
A very simple use case is given in the docxtemplateenginetest project, which is a command line application that takes an input filename,
an output filename, and a JSON string. Eg:
docxtemplateenginetest.exe template.docx output.docx "{ Name: 'Ben', Website: 'swxben.com' }"
If the data contains a null value for a given property, the template field will be replaced with an empty value (""). If the data doesn't contain a template field, the field won't be replaced at all.
The templating language in the first milestone is a simple search and replace using the value .ToString(). No escaping of the
template sequence, loops, formatting in document etc. The template probably won't be recognised if there is any formatting within
the template string such as an errant bold character like {{this}}. There are also issues with UTF8 encoding and characters such as em dash which are currently solved just by replacing the errant characters which isn't ideal.
- Safe handling of null values in the source data (@MarkKGreenway)
- Read from stream (@MarkKGreenway)
- Simple search and replace as given in the first example.
- Originally I wanted plain text templates such as
[[Name]]or{{Name}}but Word likes to insert runs for things like grammar warnings, so sticking to merge fields for now
- NuGet package
- Nested objects, eg
{{Address.Line1}} {{Address.Line2}} - Formatting in the template, eg
{{DateOfBirth.ToString("dd-MM-yyyy")}}
- Flow control in the template, eg
{{foreach (var name in Names)}} {{name}}, {{endforeach}}
If you want to contribute to this project, start by forking the repo: https://github.com/swxben/docx-template-engine. Create an issue if applicable, create a branch in your fork, and create a pull request when it's ready. Thanks!
Note that the template engine implements the IDocXTemplateEngine interface, so any additions to the engine need to be reflected in the interface.
Please don't include any new versions of the NuGet package in your PR! I'll upload a new package as soon as I'm happy with the changes in the new version. But thanks for your enthusisasm ;-)
THe VS2013 solution is in the root folder. Unit tests (src\Tests\bin\Debug\Tests.dll) can be run in a console using tests.bat. The NuGet package can be built by running build-nuget-package.cmd. The NuGet build script assumes VS 2013 (VS110).
All files CC BY-SA 3.0 unless otherwise specified.
Third party libraries or resources have been included in this project under their respective licenses.
- The engine uses SharpZipLib 1 2 which is GPL with an exception meaning it can be used in commercial closed-source applications.
- The example project uses JSON.NET which uses the MIT License and is © James Newton-King.
- @bendetat (maintainer)
- @deltasem
- @MarkKGreenway