X39.Solutions.Papercraft.Core 8.1.1

X39.Solutions.Papercraft.Core

X39.Solutions.Papercraft.Core contains the renderer-neutral Papercraft runtime. It defines the public contracts for templates, controls, data conversion, display lists, render targets, renderer capabilities and validation. It also contains the current XML parser, layout/runtime implementation, built-in controls and built-in template transformers during the Papercraft package split.

Use this package when you need Papercraft contracts without taking a dependency on SkiaSharp or the legacy compatibility package.

Package Role

This package references Microsoft.Extensions.DependencyInjection.Abstractions and intentionally does not reference SkiaSharp, hosting, OpenTelemetry or X39.Solutions.PdfTemplate.

Register Core Services

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

var services = new ServiceCollection();
var builder = services.AddPapercraftCore();

AddPapercraftCore() registers parser/runtime services, default controls, default transformers, Papercraft, PapercraftGenerator, and the compatibility PapercraftRenderer. It does not register a render backend. Normal PDF, raster, SVG or printer-command rendering through a PapercraftSession requires an IPapercraftRenderBackend registration. Lowered XML output is the exception because it stops before backend rendering:

var papercraft = serviceProvider.GetRequiredService<Papercraft>();
await using var session = papercraft.CreateSession();

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

PapercraftSessionExtensions also provides helpers such as RenderPdfAsync, GeneratePdfAsync and GenerateLoweredXmlAsync. These helpers are thin wrappers over the renderer-neutral RenderAsync target model.

Implement A Renderer

Custom renderers implement IPapercraftRenderBackend:

public sealed class MyRenderer : IPapercraftRenderBackend
{
    public RendererCapabilities Capabilities { get; } = new(
        "my-renderer",
        "My Renderer",
        RendererOutputKind.Pdf,
        new[] { PapercraftMediaTypes.ApplicationPdf });

    public ITextService TextService { get; } = new MyTextService();

    public ValueTask<RenderValidationResult> ValidateAsync(
        PapercraftDocument document,
        RenderTarget target,
        CancellationToken cancellationToken = default)
        => ValueTask.FromResult(Capabilities.ValidateTarget(target));

    public ValueTask RenderAsync(
        PapercraftDocument document,
        RenderOutput output,
        CancellationToken cancellationToken = default)
        => ValueTask.CompletedTask;

    public ValueTask RenderRasterPagesAsync(
        PapercraftDocument document,
        RasterPageRenderOutput output,
        CancellationToken cancellationToken = default)
        => ValueTask.CompletedTask;
}

TextService is the backend-specific text measurement and text display-list service used while generating documents for this renderer.

Register the backend in the application service collection:

services.AddPapercraftCore();
services.AddTransient<IPapercraftRenderBackend, MyRenderer>();

Extend Template Behavior

PapercraftServiceBuilder can add, remove or replace controls and transformers:

services.AddPapercraftCore()
        .AddFunction<MyFunction>()
        .AddControl<MyControl>()
        .ReplaceTransformer<MyOldTransformer, MyNewTransformer>();

The source currently exposes the builder through AddPapercraftCore() and through facade packages such as X39.Solutions.Papercraft.

Related Projects

• X39.Solutions.Papercraft: default app-facing facade with SkiaSharp already registered.
• X39.Solutions.Papercraft.Rendering.SkiaSharp: built-in 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 Core's activity source.
• X39.Solutions.Papercraft.Controls.QrCode and X39.Solutions.Papercraft.Controls.ZXing: optional control packages that depend on Core only.