X39.Solutions.Papercraft 8.1.1

X39.Solutions.Papercraft

X39.Solutions.Papercraft is the default application-facing package for Papercraft. It combines the renderer-neutral core runtime with the SkiaSharp renderer so normal consumers can register one package and render XML templates to PDF, raster output or backend-free lowered XML diagnostics.

Use this package when you are writing an application and want the current default Papercraft stack. Use X39.Solutions.Papercraft.Core instead when you are implementing a custom renderer or building a package that must not depend on SkiaSharp.

Package Role

The package references:

• X39.Solutions.Papercraft.Core
• X39.Solutions.Papercraft.Rendering.SkiaSharp
• Microsoft.Extensions.DependencyInjection.Abstractions

Register Services

using Microsoft.Extensions.DependencyInjection;
using X39.Solutions.Papercraft;

var services = new ServiceCollection();
services.AddPapercraft();

AddPapercraft() registers the core parser, default controls, default transformers, Papercraft, the compatibility PapercraftRenderer, and the SkiaSharp render backend.

Use the overload when adding custom template behavior:

services.AddPapercraft((builder) =>
{
    builder.AddFunction<MyFunction>();
    builder.ReplaceControl<MyTextControl>();
});

Render A PDF

using System.Globalization;
using System.Xml;
using Microsoft.Extensions.DependencyInjection;
using X39.Solutions.Papercraft;

await using var provider = services.BuildServiceProvider();
var papercraft = provider.GetRequiredService<Papercraft>();
await using var session = papercraft.CreateSession();

using var reader = XmlReader.Create(templateStream);
await using var output = File.Create("document.pdf");

await session.GeneratePdfAsync(output, reader, CultureInfo.InvariantCulture);

The same session can validate templates before rendering, write page-by-page PNG raster output through RenderRasterPagesAsync, and inspect lowered XML diagnostics through ReadLoweredXmlAsync(...) or RenderAsync(..., RenderTarget.LoweredXml, ...).

Template Data

Template data belongs to the session:

session.TemplateData.SetVariable("CustomerName", "Ada Lovelace");

The template can then read @CustomerName through the template language.

Lowered XML Diagnostics

using var reader = XmlReader.Create(templateStream);

var loweredXml = await session.ReadLoweredXmlAsync(reader, CultureInfo.InvariantCulture);

PapercraftRenderer remains available as an obsolete compatibility adapter for existing code.

Related Projects

• X39.Solutions.Papercraft.Core: renderer-neutral contracts, parser, controls, data types and transformers.
• X39.Solutions.Papercraft.Rendering.SkiaSharp: default PDF and raster backend.
• X39.Solutions.Papercraft.Rendering.Svg: optional SVG vector backend.
• X39.Solutions.Papercraft.Rendering.PdfSharp: optional PDFsharp backend.
• X39.Solutions.Papercraft.Rendering.EscPos: optional ESC/POS printer-command backend.
• X39.Solutions.Papercraft.OpenTelemetry: optional host/OpenTelemetry registration for renderer activity tracing.
• X39.Solutions.PdfTemplate: compatibility bridge for existing X39.Solutions.PdfTemplate consumers.

The template-author manual lives in ../../docs/manual.