API reference

Three public types, all in the AltSoft.Xml2Pdf namespace. There is no builder, no options object and no configuration file — a renderer is created, it converts, it is disposed.

Target: net10.0-windows
Platform: Windows x64
Package: AltSoft.Xml2Pdf 1.0.0

Types at a glance

Type	Kind	Purpose
FoPdfRenderer	sealed class	Converts one XSL-FO document to PDF. Disposable.
Xml2PdfException	sealed class	The single exception for conversion failures. Carries an ErrorCode.
ErrorCode	enum	Six machine-readable failure categories.

FoPdfRenderer

Converts one XSL-FO document to PDF through the XML2PDF engine. Implements IDisposable. The engine is initialised on the first conversion, not in the constructor.

Constructor

public FoPdfRenderer(string[]? fontFolders = null)

fontFolders lists folders to search for fonts. The engine tokens %SystemFonts% and %StdPDFType1Fonts% are accepted. When null or empty, system fonts are used.

Throws PlatformNotSupportedException when the host is not Windows x64, and Xml2PdfException with FontUnavailable for a folder that does not exist, or EngineFailure when the engine cannot be created.

Convert — file to file

public void Convert(string inputPath, string outputPath)

Output is written to a temporary file in the destination directory and moved into place only after a successful render, so a failed conversion never leaves a truncated PDF at outputPath. A pre-existing file is replaced on success and left untouched on failure.

Convert — stream to stream

public void Convert(Stream input, Stream output)

The caller owns both streams: neither is disposed, on success or on failure. The input is read from its current position and need not be seekable. The output must be writable and seekable.

Stream output is not atomic. If the conversion fails part-way, partial bytes may already be in the destination — write to a buffer or a temporary file if you need the same guarantee the file overload gives you.

Dispose

public void Dispose()

Releases the engine. A disposed renderer throws ObjectDisposedException from either Convert overload.

Xml2PdfException

public sealed class Xml2PdfException : Exception
{
    public Xml2PdfException(ErrorCode errorCode, string message, Exception? innerException = null);
    public ErrorCode ErrorCode { get; }
}

The single exception raised for conversion failures. The original engine exception, when there is one, is preserved as InnerException. Platform failures are thrown as PlatformNotSupportedException instead, so a MissingInput catch will not accidentally swallow them.

ErrorCode

Value	Meaning
InvalidInput	The XSL-FO document is malformed or cannot be laid out.
MissingInput	The input file, or the input path, does not exist.
FontUnavailable	A configured font folder is unavailable, or a required font cannot be loaded.
PlatformUnsupported	The operating system or process architecture is not supported.
StreamNotUsable	A caller-supplied stream cannot satisfy the conversion contract.
EngineFailure	The PDF engine failed for a reason other than the input or the streams.

Threading and determinism

One renderer per conversion: The renderer is not thread-safe. A second concurrent call on the same instance throws InvalidOperationException. Parallelism across separate instances is not verified and is not claimed.
Layout is stable, bytes are not: The same input produces the same page geometry, but the bytes differ between runs because the PDF carries timestamps and font-subset identifiers. Compare layout, not checksums.
Fonts substitute silently: A font named by the document that cannot be resolved is replaced, and the page still renders. It is not reported as an error — inspect the output if the face matters.

Complete example

using System;
using System.IO;
using AltSoft.Xml2Pdf;

try
{
    using var renderer = new FoPdfRenderer();

    // File overload — atomic: the target is replaced only on success.
    renderer.Convert("invoice.fo", "invoice.pdf");

    // Stream overload — you own both streams.
    using var input = File.OpenRead("statement.fo");
    using var output = File.Create("statement.pdf");
    renderer.Convert(input, output);
}
catch (Xml2PdfException ex)
{
    Console.Error.WriteLine($"{ex.ErrorCode}: {ex.Message}");
    throw;
}

Requires net10.0-windows, PlatformTarget=x64 and <UseWindowsForms>true</UseWindowsForms> in the consuming project.