Regira Office.Word provides Word document creation from templates, conversion, merging, and content extraction.
| Project | Package | Backend | Create | Convert | Merge | Extract |
|---|---|---|---|---|---|---|
Common.Office |
(transitive) | Shared abstractions | — | — | — | — |
Word.Spire |
Regira.Office.Word.Spire |
FreeSpire.Doc, or Spire.Doc | ✓ | ✓ | ✓ | ✓ |
Word.Syncfusion |
Regira.Office.Word.Syncfusion |
Syncfusion DocIO | ✓ | ✓ except EPUB | ✓ | ✓ |
Word.Aspose |
Regira.Office.Word.Aspose |
Aspose.Words | ✓ | ✓ | ✓ | ✓ |
Word.Mini |
Regira.Office.Word.Mini |
MiniWord | partial | — | — | text, images |
Word.Gotenberg |
Regira.Office.Word.Gotenberg |
Gotenberg server (LibreOffice) | — | PDF only | — | page images |
<!-- Full-featured (recommended) -->
<PackageReference Include="Regira.Office.Word.Spire" Version="6.*" />
<!-- Full-featured, commercial licence -->
<PackageReference Include="Regira.Office.Word.Syncfusion" Version="6.*" />
<!-- Full-featured, loads ODT and writes EPUB, commercial licence -->
<PackageReference Include="Regira.Office.Word.Aspose" Version="6.*" />
<!-- Lightweight: create and extract, no vendor licence -->
<PackageReference Include="Regira.Office.Word.Mini" Version="6.*" />
<!-- PDF conversion and page images through a Gotenberg server, no vendor licence -->
<PackageReference Include="Regira.Office.Word.Gotenberg" Version="6.*" />
IWordService word = new Regira.Office.Word.Spire.WordService();
byte[] templateBytes = await File.ReadAllBytesAsync("template.docx");
IMemoryFile doc = await word.Create(new WordTemplateInput
{
Template = templateBytes.ToMemoryFile(),
GlobalParameters = new Dictionary<string, object>
{
["CustomerName"] = "Alice",
["InvoiceDate"] = DateTime.Today.ToString("d")
}
});
Task<IMemoryFile> Create(WordTemplateInput input, CancellationToken cancellationToken = default);
Task<IMemoryFile> Convert(WordTemplateInput input, FileFormat format, CancellationToken cancellationToken = default);
Task<IMemoryFile> Convert(WordTemplateInput input, ConversionOptions options, CancellationToken cancellationToken = default);
The returned file’s ContentType names the format produced — application/pdf for FileFormat.Pdf, text/html for Html — so a web action can serve it with that type.
Task<IMemoryFile> Merge(IEnumerable<WordTemplateInput> inputs, CancellationToken cancellationToken = default);
Each input is created, then joined to the previous one: it starts on a new page and keeps its own section breaks. An input with EnforceEvenAmountOfPages starts on an odd page, and so does the one after it. A backend’s DocumentBuilder joins the inputs it Loads the same way. To run one document on inside another, without a page break, insert it as a nested document (DocumentParameters).
Task<string> GetText(WordTemplateInput input, CancellationToken cancellationToken = default);
Task<IEnumerable<WordImage>> GetImages(WordTemplateInput input, CancellationToken cancellationToken = default);
Task<IEnumerable<IImageFile>> ToImages(WordTemplateInput input, CancellationToken cancellationToken = default); // one image per page
Composite of all the above. Word.Spire.WordService, Word.Syncfusion.WordService and Word.Aspose.WordService implement this. Word.Mini.WordService implements IWordCreator, IWordTextExtractor and IWordImageExtractor only, and Word.Gotenberg.WordService implements IWordConverter and IWordToImagesService only, so depend on the narrowest interface you need. IWordManager : IWordService is an [Obsolete] alias — depend on IWordService.
| Property | Type | Description |
|---|---|---|
Template |
IMemoryFile |
Source .docx template |
GlobalParameters |
IDictionary<string, object>? |
Simple {{Key}} replacements; also decide {{#if Key}} conditional blocks |
CollectionParameters |
IDictionary<string, ICollection<IDictionary<string, object>>>? |
Rows — the key is the Alt Text title of the table they fill or the key a {{#each Key}} loop runs over; {{#if Key}} holds when it has rows |
Images |
ICollection<WordImage>? |
Image replacements (matched by name) |
DocumentParameters |
IDictionary<string, WordTemplateInput>? |
Nested documents, each inserted in place of a <{ key }> placeholder paragraph |
Headers |
ICollection<WordHeaderFooterInput>? |
Page headers |
Footers |
ICollection<WordHeaderFooterInput>? |
Page footers |
Options |
InputOptions? |
Processing behaviour flags |
| Property | Type | Default | Description |
|---|---|---|---|
InheritFont |
bool |
false |
Apply template’s Normal style font to inserted content |
HorizontalAlignment |
HorizontalAlignment? |
null |
Force text alignment |
RemoveEmptyParagraphs |
bool |
false |
Strip blank paragraphs after substitution |
EnforceEvenAmountOfPages |
bool |
false |
Insert page break if page count is odd, counted in the font InheritFont gives; merged, the input starts on an odd page and so does the next one |
| Property | Type | Default | Description |
|---|---|---|---|
OutputFormat |
FileFormat |
Docx |
Target format |
AutoScaleTables |
bool |
true |
Resize tables to fit new page width |
AutoScalePictures |
bool |
true |
Scale pictures by as much as the text width changes, keeping their proportions, up to Word’s 22-inch shape limit; a picture already past it is brought to it. A picture inside a text box keeps its size |
Settings |
DocumentSettings? |
null |
Override page size / orientation / margins of every section — a document mixing portrait and landscape sections comes out in one orientation |
| Property | Type | Default | Description |
|---|---|---|---|
PageSize |
PageSize |
A4 |
Paper format; A0, A1 and A2 pass Word’s 22-inch page limit, so a PDF or page images take them but Word misreads a .docx written at them |
PageOrientation |
PageOrientation |
Portrait |
Orientation |
Margins |
Margins? |
null |
Override margins (in points) |
Docx Doc Dotx Dot Docm Dotm Pdf Html Rtf Odt EPub Jpeg Png
| Property | Type | Description |
|---|---|---|
Name |
string |
Matches image placeholder name in the template |
File |
IMemoryFile? |
Image bytes |
Size |
ImageSize? |
Picture size: Word.Mini gives the picture it inserts this size (400 × 400 without one); Word.Spire, Word.Syncfusion and Word.Aspose keep the size of the template picture they replace |
HorizontalAlignment |
HorizontalAlignment? |
Picture alignment; a replaced template picture keeps its own |
| Property | Type | Description |
|---|---|---|
Template |
WordTemplateInput |
The header/footer’s own template input: its parameters fill it, and its blocks read them, not the main input’s |
Type |
HeaderFooterType |
Default, FirstPage, Even, Odd — FirstPage and Even give those pages stories of their own, headers and footers alike: the Default story then serves the other pages, and a story given no FirstPage/Even version repeats its default on those pages |
On Word.Spire, Word.Syncfusion and Word.Aspose, a CollectionParameters entry fills the table whose Alt Text title
(Table Properties → Alt Text → Title) is its key. The table’s second row is the template row: it is written once per
row of the collection, in order, and the rows around it stay where they are — a header above it, a totals row below it:
Alt Text title: Lines
| Nr | Description | Price |
| {{ row_number }} | {{ Description }} | € {{ Price }} |
| Total | | {{ Total }} |
IWordService word = new Regira.Office.Word.Spire.WordService();
byte[] templateBytes = await File.ReadAllBytesAsync("order.docx");
var orderLines = new[] { (Description: "Consulting", Price: 1000m), (Description: "Travel", Price: 250m) };
IMemoryFile doc = await word.Create(new WordTemplateInput
{
Template = templateBytes.ToMemoryFile(),
GlobalParameters = new Dictionary<string, object> { ["Total"] = orderLines.Sum(l => l.Price).ToString("N2") },
CollectionParameters = new Dictionary<string, ICollection<IDictionary<string, object>>>
{
["Lines"] = orderLines.Select(l => (IDictionary<string, object>)new Dictionary<string, object>
{
["Description"] = l.Description,
["Price"] = l.Price.ToString("N2")
}).ToList()
}
});
{{ Total }} above is filled from GlobalParameters.{{ row_number }} is the row’s position, from 1. Every other tag in the template row reads the collection row,
regardless of case, and a tag the row does not have is left empty — a GlobalParameters key included, so keep
global values out of the template row. A tag whose key holds anything but ASCII letters, digits, _ and . is
not a row field and is left for GlobalParameters.ToString(): format numbers, amounts and dates in code.IWordCreator.Word.Spire, Word.Syncfusion, Word.Aspose and Word.Mini keep or drop a stretch of a template depending on a parameter. Each marker stands alone in its own paragraph:
{{#if IsPaid}}
Thank you for your payment of {{Amount}}.
{{else}}
Please pay {{Amount}} before {{DueDate}}.
{{/if}}
IWordService word = new Regira.Office.Word.Spire.WordService();
byte[] templateBytes = await File.ReadAllBytesAsync("invoice.docx");
DateTime dueDate = DateTime.Today.AddDays(30);
decimal amountPaid = 0m;
IMemoryFile doc = await word.Create(new WordTemplateInput
{
Template = templateBytes.ToMemoryFile(),
GlobalParameters = new Dictionary<string, object>
{
["IsPaid"] = amountPaid > 0,
["Amount"] = "€ 1 250,00",
["DueDate"] = dueDate.ToString("d")
}
});
{{#if Key}} holds when GlobalParameters[Key] is set to anything but null, false, an empty or blank
string, zero or an empty collection. The texts "false" and "0" hold: convert a form or query-string value to
bool before passing it. A JSON value is read by its kind, so a JSON false, 0, [] or {} is false. An enum
value always holds, its zero member included: compare it in code (["IsDraft"] = status == Status.Draft). A
CollectionParameters key holds when its collection has rows, so {{#if Items}} drops a heading together with
its empty table. A key found in neither is false, and keys match regardless of case, an exact match first.{{#if !Key}} negates. {{else}} is optional, and blocks nest.<{ key }> placeholder — and
the marker paragraphs go too, whichever branch holds, with anything else they carry: a page break, a bookmark, a
picture anchored to one. Keep those in a paragraph of their own; only a section break stored on a marker
paragraph stays. Blocks are resolved before anything is filled, so a dropped branch’s parameters, images and
nested documents are never processed.["IsOverdue"] = dueDate < DateTime.Today).WordHeaderFooterInput’s template reads that Template’s parameters, not the main input’s.{{#if Key}}, {{#if !Key}} or {{#each Key}} and nothing
else, and only then are its blocks resolved. Everything else in a document that uses none stays as it is — marker
text among other text, a stray {{else}}, {{/if}} or {{/each}} — so a finished document that writes about
templates converts and reads unchanged.Create fills is read as a template by any later call. A parameter value that fills a paragraph
with nothing but a marker — {{#if X}} typed into a form — makes that output use blocks: a later GetText,
Convert or ToImages of it throws, or drops everything between two such values. Keep user-entered values out
of paragraphs of their own, or produce the final format in the call that fills the template, rather than
converting the stored output later.FormatException: a block that does not open and close in one
container and section, a closer or {{else}} without its opener, a {{/if}} closing a loop or a {{/each}} a
condition, a second {{else}}, blocks nested more than 100 levels deep in one container, a marker sharing its
paragraph with other text, and a marker this syntax does not know, such as {{#unless X}}, {{else if X}} or
{{#each !X}}.Word.Spire, Word.Syncfusion, Word.Aspose and Word.Mini write a stretch of a template once per row of a collection. The markers follow the rules of conditional blocks — each stands alone in its own paragraph, within one container and section — and loops and conditions nest in each other:
{{#each Orders}}
Order {{Number}} of {{Date}}
{{#if Note}}
{{Note}}
{{/if}}
{{#each Lines}}
{{row_number}}. {{Description}}: {{Price}}
{{/each}}
{{else}}
There are no orders this month.
{{/each}}
IWordService word = new Regira.Office.Word.Spire.WordService();
byte[] templateBytes = await File.ReadAllBytesAsync("orders.docx");
IMemoryFile doc = await word.Create(new WordTemplateInput
{
Template = templateBytes.ToMemoryFile(),
CollectionParameters = new Dictionary<string, ICollection<IDictionary<string, object>>>
{
["Orders"] =
[
new Dictionary<string, object>
{
["Number"] = "A-1",
["Date"] = new DateTime(2026, 10, 1).ToString("d"),
["Note"] = "Fragile",
["Lines"] = new[] { new { Description = "Pen", Price = "€ 5,00" }, new { Description = "Ink", Price = "€ 15,00" } }
},
new Dictionary<string, object> { ["Number"] = "A-2", ["Date"] = new DateTime(2026, 10, 3).ToString("d") }
]
}
});
{{#each Key}} runs over CollectionParameters[Key], matched regardless of case, an exact match first. Inside a
loop, the key can also name a field of the current row, or of a row around it, that holds a list of rows —
dictionaries, objects read one level deep, or a JSON array — so {{#each Lines}} above runs over each order’s lines. A key that names
no list of rows — a missing key, a GlobalParameters entry, a field holding one value — gives no rows, and the
optional {{else}} part is written instead.{{Field}} reads the current row, then the rows of the loops around it, innermost first, regardless
of case. A field none of them has is left for GlobalParameters, so {{Currency}} still reaches a global value.
{{ row_number }} is the current row’s position, from 1.{{#if Key}} inside a loop reads the same rows first, then the input, so it decides per row.ToString(), a line ending becoming a line break, as a global one is; an
html_ key in a row is text too. Format numbers,
amounts and dates in code. A value is never read as a marker: a row whose Number is {{/each}} writes that text.
It may be read as a field, though, as a global or collection-table value may: a row value holding a {{Field}} tag
of its row, or a {{Key}} or <{ key }> tag of GlobalParameters or nested documents, which are filled after the
rows, is filled too, and on Word.Mini any tag in it is rewritten as
MiniWord reads tags ({{ Code }} comes out as {{Code}}). Keep user-entered text that may hold one out of row
fields.FormatException.{{#each Orders}} inside itself
writes every order once per order. Nothing caps the output, so the template decides how large the document gets:
fill templates you trust.{{Items.Name}} row, reads the
top-level CollectionParameters entry even inside a loop, and only the first table with the title is filled:
inside a loop, use marker rows. One key can feed a titled table and a loop alike.Images are matched by name across the whole document, and html_ keys are read from GlobalParameters only: a
row’s fields are text.A table row whose only text is a single marker, in any one of its cells — in a content control there or not; a text box’s text is its own — opens, divides or closes a block over the table’s rows. A row-level content control, a repeating section, is a container of rows of its own, as a content control around paragraphs is: a block around it keeps or copies its rows together, and marker rows inside it open and close their block there. The rows between are written once per item, a condition keeps or drops rows per item, and the marker rows go; a table left without rows goes:
| Description | Qty | Price |
| {{#each Lines}} | | |
| {{Description}} | {{Qty}} | {{Price}} |
| {{#if Note}} | | |
| {{Note}} |
| {{/if}} | | |
| {{/each}} | | |
| Total | | {{Total}} |
WordService implements IWordService — the full capability set. Supports HTML parameters (html_* prefix in GlobalParameters injects raw HTML). Converts to PDF, HTML, RTF, ODT and EPUB, and renders pages as images with ToImages. Handles nested document insertion via DocumentParameters.
Limits: the FreeSpire.Doc free edition supports documents up to 500 paragraphs or 25 tables, and writes at most three pages of PDF. A document past either cap throws
SpireDocFreeExceptionwhen it is read or written — a template whose loop writes a table per row fails from its 26th row. Converting a longer document to PDF gives its first three pages followed by a notice page — “Spire Doc. Free version converting word documents to PDF files, you can only get the first 3 page of PDF file.” — and raises no error.ToImagesand the other formats (HTML, RTF, ODT, EPUB) carry every page. For longer PDFs, run Word.Spire on the commercial Spire.Doc, use Word.Syncfusion or Word.Aspose (licensed), or Word.Gotenberg (no vendor licence).
Word.Spire runs unchanged on the commercial Spire.Doc package, which has none of the free-edition limits. Both packages ship the same assembly — Spire.Doc, signed with the same key — so the app decides which one it loads. Reference Spire.Doc, and keep out the FreeSpire.Doc that Word.Spire depends on by referencing it directly with ExcludeAssets="all":
<PackageReference Include="Regira.Office.Word.Spire" Version="6.*" />
<PackageReference Include="Spire.Doc" Version="14.9.11" />
<!-- the FreeSpire.Doc version Word.Spire depends on; ExcludeAssets keeps its Spire.Doc.dll out of the build -->
<PackageReference Include="FreeSpire.Doc" Version="14.4.0" ExcludeAssets="all" />
Set the licence key once at startup, before the first document is processed. Without one, the commercial edition writes an evaluation warning on every page.
Spire.Doc.License.LicenseProvider.SetLicenseKey(licenseKey);
FileNotFoundException: Could not load file or assembly 'Spire.Doc, Version=…'.ExcludeAssets line. Without it both packages supply Spire.Doc.dll, and the build keeps the one with the higher version without a warning, so a Spire.Doc older than the FreeSpire.Doc dependency leaves the app on the free edition, PDF limit included.ExcludeAssets line names the version Word.Spire depends on, or a later one. A lower one fails restore with NU1605 (package downgrade); raise it when a Word.Spire update moves to a newer FreeSpire.Doc, and check the first rule again.WordService implements IWordService — the full capability set, on Syncfusion DocIO. No document size cap, and the same template features as Word.Spire (html_* parameters, collection tables by Alt-Text Title, nested documents, headers and footers).
The licence key goes to the constructor, which hands it to DocIO before the first document. In a container, register the configuration and the service under the interfaces the application injects:
using Regira.Office.Word.Syncfusion;
IServiceCollection services = new ServiceCollection();
IConfiguration configuration = new ConfigurationBuilder().Build();
services.AddSingleton(new SyncfusionWordConfig { LicenseKey = configuration["Syncfusion:LicenseKey"] });
services.AddTransient<IWordService, WordService>();
// or without a container
var word = new WordService(new SyncfusionWordConfig { LicenseKey = configuration["Syncfusion:LicenseKey"] });
The key also resolves from the SYNCFUSION_LICENSE_KEY environment variable, and is registered once per process.
Licence: required. Without a valid key DocIO prepends “Created with a trial version of Syncfusion Word library or registered the wrong key in your application” to every document, conversion and rendered page. It is ordinary body text rather than a hard failure, so check for its absence to confirm a key actually works. Document SDK is priced per developer per year with a minimum team size (Syncfusion pricing). Their Community Licence page names Document Solution SDKs among the products it covers, but the Document Solutions sales and licensing pages do not corroborate that and mention only a 30-day evaluation, so confirm eligibility with Syncfusion rather than assuming a free tier.
Format limits: ODT templates cannot be loaded (saving to ODT works) and EPUB export is unavailable on .NET Core. Both throw
NotSupportedException, as doPng/Jpegoutput (useToImages).
Rendering: PDF conversion and
ToImagesneedSyncfusion.DocIORenderer, which renders through SkiaSharp 4.150.1 and HarfBuzzSharp 14.2.1.1. On Linux, addSkiaSharp.NativeAssets.LinuxandHarfBuzzSharp.NativeAssets.Linuxat the versions ofSkiaSharpandHarfBuzzSharpthe application resolves — those two, unless another package raises them.
WordService implements IWordService — the full capability set, on Aspose.Words, with the same template features as Word.Spire (html_* parameters, collection tables by Alt-Text Title, nested documents, headers and footers). It is the one backend that both loads ODT templates and writes EPUB, and Convert writes every document format. Page settings honour every PageSize, A0 to A10.
The licence goes to the constructor, which applies it before the first document. In a container, register the configuration and the service under the interfaces the application injects:
using Regira.Office.Word.Aspose;
IServiceCollection services = new ServiceCollection();
IConfiguration configuration = new ConfigurationBuilder().Build();
services.AddSingleton(new AsposeWordConfig { LicensePath = configuration["Aspose:LicensePath"] });
services.AddTransient<IWordConverter, WordService>();
services.AddTransient<IWordTextExtractor, WordService>();
LicenseBase64 takes the licence file’s content instead, for a host that keeps it in a secret store. Without either, the ASPOSE_WORDS_LICENSE (Base64 content) and ASPOSE_WORDS_LICENSE_PATH environment variables are used. The licence is applied once per process.
When none of the four resolves — a configuration key that is missing, say — constructing WordService throws rather than produce evaluation output unnoticed. Set AllowEvaluation to accept that output, for a trial or a test run; a process that already holds a licence needs neither.
Licence: required. Without one Aspose.Words runs in evaluation mode: it puts “Created with an evaluation copy of Aspose.Words…” at the top of every document and “Evaluation Only. Created with Aspose.Words…” in place of its own headers and footers — conversions and rendered pages included — and cuts documents short after a few hundred paragraphs. The banners are ordinary text, so check for their absence, and that the end of a long document survives, to confirm a licence works. Aspose sells developer, site and metered licences, which differ in the number of developers and locations and in whether public-facing web apps and SaaS are covered (Aspose.Words for .NET pricing). A free 30-day temporary licence is available on request.
Format limits:
ConvertthrowsNotSupportedExceptiononly forPng/Jpegoutput (useToImages).
Rendering: PDF conversion and
ToImagesrender through SkiaSharp (3.119 or later). On Linux, addSkiaSharp.NativeAssets.Linuxat the version ofSkiaSharpthe application resolves, and installlibfontconfig1andlibharfbuzz-icu0.
WordService implements IWordCreator, IWordTextExtractor and IWordImageExtractor (WordCreator is an [Obsolete] alias). Lightweight and Apache-2.0-licensed, with no document size cap. Text and image extraction read the rendered document through the Open XML SDK, which MiniWord already depends on.
Convert, Merge and ToImages are unavailable: MiniWord has no layout engine. Use Word.Spire for those, or pair Word.Mini with Word.Gotenberg for PDF output and page images. For PDF output in-process, without a server, hand Word.Mini’s .docx to PDF.MiniPdf, whose own layout engine is less faithful to Word than LibreOffice.
Create renders GlobalParameters, CollectionParameters and Images, and throws NotSupportedException for DocumentParameters, Headers, Footers and any non-default InputOptions.
Template syntax: MiniWord’s, not Word.Spire’s. Every value fills a
{{tag}}: a collection fills a table row whose cells hold{{Items.Name}}tags, and the row repeats per item (there is no{{ row_number }}); an image replaces a{{logo}}tag rather than a picture named by its Alt Text. A template written for the other backends renders its global parameters the same way and leaves its collection tables and pictures as they are. Spaces inside the braces are ignored, and a tag Word split over several runs while it was edited still matches. Conditional blocks and loops work as on the other backends,{{ row_number }}included, because Word.Mini resolves them before MiniWord renders; use them rather than MiniWord’s own@ifparagraphs, which comparetrue/falseas text (@if Flag == truenever holds), throw on a bare@if Flag, and read only keys of letters, digits and_.
Keys: MiniWord builds a regular expression from every key, so a key it would read as a pattern throws
ArgumentExceptionnaming it. No key — a global key, an image name, a collection’s key or its fields, a loop’s too — may hold any of. \ ^ $ | ? * + ( ) [ ] { }:{{ Total EUR }}and{{ Order Lines.Unit Price }}work,{{ Total (EUR) }}does not.
Shared template namespace:
GlobalParameters,ImagesandCollectionParametersall resolve against the same{{tag}}placeholders, so a key may appear in only one of them — a duplicate throwsArgumentException.
WordService implements IWordConverter and IWordToImagesService, through the LibreOffice route of a Gotenberg server (MIT, a Docker image bundling LibreOffice and Chromium). It is the route to PDF output and page images without a vendor licence.
Convert produces PDF; every other FileFormat throws NotSupportedException. Sources can be Word (.doc, .dot, .docx, .dotx, .docm, .dotm), OpenDocument (.odt, .ott), .rtf, .txt, .html/.htm or .epub — the format is read from the file name when the template is a named file, otherwise from its content.GlobalParameters, CollectionParameters, Images, DocumentParameters, Headers, Footers or non-default InputOptions is rendered first by the IWordCreator the service was given, and throws NotSupportedException without one. So is an OOXML template holding a conditional block or a loop, even without parameters, since a key the input does not give is false and gives no rows. Word.Mini renders the first three, in its own template syntax; headers, footers, nested documents and input options need a creator with a document model — Word.Spire, Word.Syncfusion or Word.Aspose — since Word.Mini refuses them. An OOXML source converted without parameters is scanned for such a block in-process, and one whose parts hold more than 32 MiB together, uncompressed and images included, or that has more than 1,000 parts, is not opened: it is uploaded as it is, its blocks unresolved, as is one the scan cannot read.ConversionOptions.Settings is written into the document’s section properties before upload, together with the table and picture scaling. That needs an OOXML source (.docx, .dotx, .docm, .dotm), and honours every PageSize.ToImages converts to PDF and hands the result to the IPdfToImageService the service was given — Regira.Office.PDF.PdfPig, for example — which returns one image per page.Start a server and register the service:
docker run --rm -p 3000:3000 gotenberg/gotenberg:8
using Regira.Media.Drawing.Services.Abstractions;
using Regira.Office.PDF.Abstractions;
using Regira.Office.Word.Gotenberg.DependencyInjection;
IServiceCollection services = new ServiceCollection();
IConfiguration configuration = new ConfigurationBuilder().Build();
// optional collaborators, taken from the container when present
services.AddSingleton<IImageService, Regira.Drawing.SkiaSharp.Services.ImageService>();
services.AddSingleton<IPdfToImageService, Regira.Office.PDF.PdfPig.PdfService>(); // for ToImages
services.AddSingleton<IWordCreator, Regira.Office.Word.Mini.WordService>(); // for template input
services.AddGotenbergWord(o =>
{
o.BaseUrl = configuration["Gotenberg:BaseUrl"] ?? "http://localhost:3000";
o.Timeout = TimeSpan.FromMinutes(2);
});
AddGotenbergWord registers IWordConverter and IWordToImagesService on one HttpClient, named ServiceCollectionExtensions.HttpClientName — add handlers or resilience through services.AddHttpClient(ServiceCollectionExtensions.HttpClientName). Username and Password send basic authentication, for a server started with --api-enable-basic-auth; ImageOptions sets the size and format of the page images. Without DI, construct WordService with an HttpClient whose BaseAddress points at the server.
Beside
AddOfficeClients: the two keep separate clients, so neither’s base address or credentials reach the other’s server. Both register anIWordConverter, and the one registered last is resolved: callAddGotenbergWordafterAddOfficeClientsto convert with Gotenberg while the Regira Office API serves the rest — itsIPdfToImageServiceincluded.
Timeouts: the server enforces its own limit per request (
--api-timeout, 30 seconds by default) and answers503when a conversion exceeds it; the exception message says so. Raise it on the server as well asTimeouthere for large documents.
HTML to PDF: the same server converts HTML through its Chromium route.
Regira.Office.PDF.GotenbergregistersIHtmlToPdfServicewithAddGotenbergPdf, on a client of its own — see Gotenberg in the PDF notes.
WordClient, in Regira.Office.Clients, implements IWordCreator, IWordConverter, IWordMerger and IWordTextExtractor against a Regira Office API, registered with AddOfficeClients.
WordTemplateInput travels as JSON: parameters, nested documents, headers, footers, Options, and each image with its Size and HorizontalAlignment.OutputFormat, Settings.PageSize, AutoScaleTables and AutoScalePictures. The API’s conversion takes no orientation or margins: it lays every section out in portrait on that page size — A4 when Settings is null — and keeps the document’s margins, so a landscape document comes back in portrait. Settings asking for Landscape or for Margins throws NotSupportedException. Jpeg and Png come back as one ZIP of page images.InheritFont on a merge input has no document to inherit from, and EnforceEvenAmountOfPages on one of several inputs throws NotSupportedException: the API starts that input and the next one on a new page, where an in-process merge starts both on an odd page, and the padding page is lost.Where orientation, margins, font inheritance or page padding across merged documents matter, use an in-process backend, or Word.Gotenberg for PDF output beside AddOfficeClients.