Fluent syntax Leave feedback
On this page
The fluent API composes a conversion as a single chained expression. It’s implemented by the FluentConverter class and the staged interfaces in the GroupDocs.Conversion.Fluent namespace — each call returns a new stage interface that exposes only the methods valid for the next step.
A fluent chain moves through four stages:
| Stage | Purpose | Methods |
|---|---|---|
| Entry | Configure the converter before any source is opened | WithSettings(...), WithEvents(...) |
| Load | Specify the source and (optionally) load options | Load(...), WithOptions(LoadOptions) |
| Convert | Specify the target and conversion options | ConvertTo(...), ConvertByPageTo(...), WithOptions(ConvertOptions), Compress(...) |
| Terminal | Execute the operation | Convert(), GetDocumentInfo(), GetPossibleConversions() |
Entry-stage calls are optional; the shortest valid chain skips straight to Load(...).
The minimal chain — load a file, name the target, run:
FluentConverter
.Load("sample.docx")
.ConvertTo("converted.pdf")
.Convert();
Add load and convert options when you need them:
FluentConverter
.Load("sample.pdf").WithOptions(new PdfLoadOptions())
.ConvertTo("converted.docx").WithOptions(new WordProcessingConvertOptions())
.Convert();
Use WithSettings(...) to customize the ConverterSettings — for example, to set a logger or cache:
FluentConverter
.WithSettings(() => new ConverterSettings { Logger = new ConsoleLogger() })
.Load("sample.docx")
.ConvertTo("converted.pdf")
.Convert();
Use WithEvents(...) to register handlers on the ConversionEvents aggregator — see Subscribing to conversion events below.
Both entry-stage calls are optional and can be combined in either order:
FluentConverter
.WithSettings(() => new ConverterSettings { Logger = new ConsoleLogger() })
.WithEvents(e => e.OnDocumentConverted = ctx => Console.WriteLine($"Done: {ctx.SourceFileName}"))
.Load("sample.docx")
.ConvertTo("converted.pdf")
.Convert();
Use ConvertByPageTo(...) to write each source page to its own stream:
FluentConverter
.Load("sample.pdf").WithOptions(new PdfLoadOptions())
.ConvertByPageTo((SavePageContext ctx) => new FileStream($"converted-{ctx.Page}.docx", FileMode.Create))
.WithOptions(new WordProcessingConvertOptions())
.Convert();
The stream factory receives a SavePageContext with the page number and source format — return a fresh stream for each call.
Two terminal methods replace Convert() when you need information about the source rather than a converted output:
// Available target formats for this source
IReadOnlyList<PossibleConversions> possible = FluentConverter
.Load("sample.pdf")
.GetPossibleConversions();
// Format-specific metadata (page count, properties, etc.)
IDocumentInfo info = FluentConverter
.Load("sample.pdf")
.GetDocumentInfo();
Both accept a load-options stage if the source needs one:
FluentConverter.Load("sample.pdf").WithOptions(new PdfLoadOptions()).GetPossibleConversions();
FluentConverter.Load("sample.pdf").WithOptions(new PdfLoadOptions()).GetDocumentInfo();
Convert() accepts a CancellationToken for timeout or user-driven cancellation — see Cancellation for the full pattern:
using var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromSeconds(60));
FluentConverter
.Load("sample.dwg")
.ConvertTo("converted.pdf").WithOptions(new PdfConvertOptions())
.Convert(cts.Token);
Since version 26.6, event handlers are registered through the ConversionEvents aggregator via the entry-stage WithEvents(...) method. The aggregator covers both pipeline lifecycle events (OnConversionStarted / OnConversionProgress / OnConversionCompleted) and per-result events (OnDocumentConverted / OnDocumentFailed / OnPageConverted / OnPageFailed / OnCompressionCompleted):
FluentConverter
.WithEvents(e =>
{
e.OnConversionStarted = () => Console.WriteLine("Conversion started");
e.OnConversionProgress = percent => Console.WriteLine($"... {percent}% ...");
e.OnDocumentConverted = ctx => Console.WriteLine($"Done: {ctx.SourceFileName}");
e.OnDocumentFailed = (ctx, ex) => Console.WriteLine($"Failed: {ex.Message}");
e.OnPageFailed = (ctx, ex) => Console.WriteLine($"Page failed: {ex.Message}");
})
.Load("sample.docx")
.ConvertTo("converted.pdf").WithOptions(new PdfConvertOptions())
.Convert();
The previous late-stage chain methods (.OnConversionCompleted(...).OnConversionFailed(...) placed after WithOptions(...), and .OnCompressionCompleted(...) placed after .Compress(...)) continue to work but are obsolete and planned for removal in v26.9. See the Conversion events guide for the full migration story, including the rename of per-result handlers from OnConversion* to OnDocument* / OnPage*.
- Conversion events — full reference for
WithEvents(...)andConversionEvents - Context Objects — Complete Guide — properties exposed by
SaveContext,SavePageContext,ConvertedContext, etc. - Cancellation — passing a
CancellationTokenthrough the fluent chain - Extract and Convert Archive Contents —
Compress(...)andOnCompressionCompleted
Was this page helpful?
Any additional feedback you'd like to share with us?
Please tell us how we can improve this page.
Thank you for your feedback!
We value your opinion. Your feedback will help us improve our documentation.
