OpenXmlForge 1.0.0
See the version list below for details.
dotnet add package OpenXmlForge --version 1.0.0
NuGet\Install-Package OpenXmlForge -Version 1.0.0
<PackageReference Include="OpenXmlForge" Version="1.0.0" />
<PackageVersion Include="OpenXmlForge" Version="1.0.0" />
<PackageReference Include="OpenXmlForge" />
paket add OpenXmlForge --version 1.0.0
#r "nuget: OpenXmlForge, 1.0.0"
#:package OpenXmlForge@1.0.0
#addin nuget:?package=OpenXmlForge&version=1.0.0
#tool nuget:?package=OpenXmlForge&version=1.0.0
OpenXmlForge
OpenXmlForge is a modern, high-performance .NET Word (.docx) template engine built on top of DocumentFormat.OpenXml.
Designed from the ground up for modern .NET (.NET 10+), OpenXmlForge focuses on low memory allocation, high throughput, and predictable resource usage while keeping a clean, declarative {{tag}} template syntax.
Quick Start
Generate a MemoryStream (Async / Sync)
using OpenXmlForge;
await using var templateStream = File.OpenRead("template.docx");
var data = new
{
Order = new { Number = "ORD-2026-001", Date = DateTime.UtcNow },
Customer = new { LegalName = "Acme Industrial Ltd", VIP = true },
Items = new[]
{
new { Sku = "P-100", Description = "Industrial Servo Motor", Quantity = 2, Price = "$ 1,200.00" },
new { Sku = "P-205", Description = "Frequency Inverter", Quantity = 1, Price = "$ 850.00" }
}
};
// Returns a positioned MemoryStream (Position = 0) ready to be returned from an API or saved
await using MemoryStream output = await WordForge.GenerateStreamAsync(templateStream, data);
Save Directly to a File or Stream
using OpenXmlForge;
// Async file-to-file
await WordForge.SaveAsByTemplateAsync("output.docx", "template.docx", data);
// Sync file-to-file
WordForge.SaveAsByTemplate("output.docx", "template.docx", data);
// Extension method on any output Stream
await outputStream.SaveAsByTemplateAsync(templateStream, data);
Template Features
1. Scalar & Nested Dotted Tags
OpenXmlForge accepts IDictionary<string, object?>, anonymous types, POCOs, and ExpandoObject. Both flat keys with dots (["Customer.Name"]) and nested object graphs (new { Customer = new { Name = "..." } }) resolve seamlessly:
Invoice #{{Order.Number}}
Customer: {{Customer.LegalName}}
Notes: {{Document.Notes}}
Multiline strings (\n, \r\n) and IEnumerable<string> values automatically emit OpenXML <w:br/> line breaks while preserving run formatting.
2. Repeating Table Rows
Place collection tags ({{Collection.Property}}) inside a table row and OpenXmlForge will automatically clone the row for each item in Collection. Outer scalar variables ({{Currency}}, {{Order.Number}}) in the same row remain accessible:
| SKU | Description | Qty | Price |
|---|---|---|---|
{{Items.Sku}} |
{{Items.Description}} |
{{Items.Quantity}} |
{{Currency}} {{Items.Price}} |
3. Block & Inline Loops (@foreach / {{foreach}})
Block @foreach (repeats paragraphs and tables between @foreach and @endforeach):
@foreach(item in Items)
- {{item.Description}} ({{item.Quantity}}x)
@endforeach
Inline {{foreach}} (repeats text within a single paragraph):
Tags: {{foreach item in Tags}}[{{item.Name}}] {{endforeach}}
Or using WordForeach with custom separators:
using OpenXmlForge.Models;
var data = new Dictionary<string, object?>
{
["Tags"] = new WordForeach
{
Value = new[]
{
new { Tags = "Urgent" },
new { Tags = "Priority" }
},
Separator = " | "
}
};
4. Conditional Blocks & Inline Statements (@if / {{if}})
Supports ==, !=, >, <, >=, <= across numbers, DateTime, booleans, and strings.
Block @if:
@if(Total > 1000)
Approved for Executive Discount
@endif
Inline {{if}}:
Status: {{if(IsActive == true) ACTIVE endif}}{{if(IsActive == false) INACTIVE endif}}
5. Images (WordPicture)
Embed images from a Stream (including non-seekable streams), byte[], or file path. When Width and Height are omitted, OpenXmlForge reads the natural dimensions from the image header and proportionally clamps the image to fit the containing table cell width if placed inside a table.
using OpenXmlForge.Models;
var data = new Dictionary<string, object?>
{
// Auto-sized from image header (and clamped to table cell width if inside a table)
["ProductImage"] = new WordPicture(imageStream),
// Explicit dimensions in pixels
["CompanyLogo"] = new WordPicture("logo.png", width: 160, height: 60),
// Floating / anchored image
["Watermark"] = new WordPicture(watermarkBytes, "png", width: 300, height: 300)
{
WrappingType = WordPictureWrappingType.Anchor,
BehindDoc = true,
HorizontalPositionOffset = 100,
VerticalPositionOffset = 200
}
};
6. Hyperlinks (WordHyperLink) & Colored Text (WordColorText)
using OpenXmlForge.Models;
var data = new Dictionary<string, object?>
{
["PortalLink"] = new WordHyperLink
{
Url = "https://example.com/orders/1042",
Text = "View Order in Portal",
TargetFrame = TargetFrameType.Blank
},
["StatusBadge"] = new WordColorText
{
Text = "APPROVED",
FontColor = "#FFFFFF",
HighlightColor = "#16A34A"
}
};
Building & Testing
dotnet build OpenXmlForge.slnx
dotnet test OpenXmlForge.slnx
Why OpenXmlForge?
Modern .NET Capabilities & Performance
- Source-Generated Regex & Span Parsing: Uses
[GeneratedRegex],ReadOnlySpan<char>,ReadOnlySpan<byte>, andstackallocbuffers for tag normalization and statement evaluation with minimal heap allocations. - Compiled Expression Tree Accessors: POCO and anonymous object properties are accessed via cached, compiled
Expression.Lambdadelegates (ConcurrentDictionary<Type, PropertyAccessor[]>) instead of repeated runtime reflection, paired withFrozenSet<T>andStringComparer.Ordinallookups. - Single-Pass DOM Tag Defragmenter: Word, Google Docs, and LibreOffice frequently split
{{Variable.Name}}tags across multiple<w:r>/<w:t>runs and inject<w:proofErr>spellcheck nodes. OpenXmlForge heals fragmented tags and@foreach/@ifdirectives in a single pass directly over the OpenXML DOM—without serializing the document to strings or running full-document regex passes.
Resource Efficiency & Streaming-First Design
- Zero-Decode Image Header Inspection: Extracts natural image dimensions (
PNG,JPEG,BMP,GIF,WebP) and detects formats by magic bytes usingBinaryPrimitivesdirectly from the header—zero pixel decoding and no heavy imaging dependencies (System.Drawing,SkiaSharp, orImageSharpare not required). - Non-Seekable & Network Stream Support: Accepts non-seekable streams (such as
HttpClientresponse streams or cloud object storage streams) for both templates and images using a lightweightPrefixedStreamwrapper that replays the inspected header bytes before streaming the rest of the payload directly into the OpenXML package. - Concurrent Async Image Preparation & Deterministic Disposal: Prepares image streams concurrently in async workflows and automatically disposes owned image streams when template generation finishes (configurable via
LeaveStreamOpen). - Pre-Sized Output Buffers: Estimates output
MemoryStreamcapacity upfront when template length is known to avoid repeated large buffer reallocations.
Advanced Layout & Document Correctness
- Automatic Table Cell Image Clamping: Measures usable cell width across explicit
dxa, fractional Google Docs widths,pctpercentage widths,w:tblGrid+w:gridSpan, and page margins—proportionally scaling oversized images so they never overflow table columns while keeping small icons at their natural size. - Unlimited Dotted Variables & Multi-Collection Rows: Freely mix any number of dotted scalar paths (
{{Order.Number}},{{Customer.LegalName}},{{Address.City}}) and repeating collection bindings in the same table row. - Vertical Merge (
<w:vMerge/>) Row Grouping: Automatically groups consecutive vertically merged rows and clones the entire group per collection item. - Isolated Shape & TextBox Scopes: Processes
<w:txbxContent>shapes from innermost to outermost so multiline text and tags insidemc:AlternateContent(Choice/Fallback) never leak into outer paragraphs.
Acknowledgments
OpenXmlForge was inspired by MiniWord, reimagined from the ground up with a new architecture focused on modern .NET capabilities, streaming resource efficiency, and OpenXML layout accuracy.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- DocumentFormat.OpenXml (>= 3.5.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.