Quick start.

02File conversion

The shortest path: one renderer, one call. The file appears at your output path only after the render succeeds — the library writes a temp file in the destination directory and moves it into place.

using AltSoft.Xml2Pdf;

using var renderer = new FoPdfRenderer();
renderer.Convert("invoice.fo", "invoice.pdf");

The input is XSL-FO. Getting to know XSL-FO is the shortest introduction to the vocabulary, and XSL-FO document structure walks through the root element, the page masters and the flow that carry the content.

03Stream conversion

For documents you generate in memory, hand over streams instead of paths.

using var fo = File.OpenRead("invoice.fo");
using var pdf = File.Create("invoice.pdf");

using var renderer = new FoPdfRenderer();
renderer.Convert(fo, pdf);

The input stream does not need to be seekable. The output stream must be writable and seekable.

04Platform requirements

The platform surface is deliberately narrow. Anything outside it fails immediately rather than half-working.

Target framework   net10.0-windows
Platform           Windows x64
Runtime            Microsoft.WindowsDesktop.App
Project flag       <UseWindowsForms>true</UseWindowsForms>
NuGet dependencies none

On a non-Windows or non-x64 host the constructor throws PlatformNotSupportedException — before any document is read.

05Error handling

Conversion failures raise Xml2PdfException with an ErrorCode you can switch on. Platform failures are separate: they are not wrapped in Xml2PdfException.

// inPath / outPath: the .fo input and the .pdf output for this call
try
{
    using var renderer = new FoPdfRenderer();
    renderer.Convert(inPath, outPath);
}
catch (Xml2PdfException ex)
{
    switch (ex.ErrorCode)
    {
        case ErrorCode.MissingInput:    // nothing at that path
        case ErrorCode.InvalidInput:    // document rejected
        case ErrorCode.FontUnavailable: // font could not be resolved
        case ErrorCode.StreamNotUsable: // output not writable/seekable
        case ErrorCode.EngineFailure:   // renderer failed internally
            Console.Error.WriteLine($"{ex.ErrorCode}: {ex.Message}");
            throw;
    }
}

06Fonts

System fonts are the default. Pass an array of folders to the constructor, and use the two tokens the engine understands for the platform font set.

using var renderer = new FoPdfRenderer(new[]
{
    @"C:\Corp\Fonts",
    "%SystemFonts%",
    "%StdPDFType1Fonts%"
});

An unavailable font is replaced by a substitute and the page still renders; it is not reported as a failure. Proof a representative document before you ship — the substitute decides how the page looks, not the document.

How fonts, sizes and inline text are declared in the document itself is covered by Font and text attributes.

07Threading

The renderer is not thread-safe. Use one instance per conversion; a second concurrent call on the same instance throws InvalidOperationException. Parallelism across separate instances is not claimed.

// files: the .fo documents to convert
foreach (var file in files)
{
    using var renderer = new FoPdfRenderer();
    renderer.Convert(file, Path.ChangeExtension(file, ".pdf"));
}

08Known restrictions

Documented limits, stated as they are.

• —Windows x64 only. No Linux, macOS or ARM64 build; no .NET Framework 4.8 support in this release.
• —Same input, same layout, different bytes per run — timestamps and font-subset identifiers differ between files.
• —No XSL-FO conformance level is asserted. Capability is evidenced by a 22-document regression corpus, not a compliance claim.
• —No performance targets are published. The renderer is built for correctness, not throughput.
• —One input format, one output format: XSL-FO in, PDF out. No Office, HTML, SVG or MathML.