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' }"
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.
- 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!
THe VS2010 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
.
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.