Scryber Configuration and Extension

Scryber provides a comprehensive configuration and extension system that allows you to customize behavior, add custom components, integrate with external systems, and implement code-behind logic for PDF templates.

Overview

This documentation covers the complete architecture for extending and configuring Scryber:

Document Configuration

Applies to individual document templates

• The Engine Document - Parsing a template into an engine Document, configuring it, and generating it with the document builder
• Processing Instructions - Document-level parser configuration via XML processing instructions
• DOM and Event Handling - Directly accessing content and responding to document remote file request events
• Working in Code - Building and modifying component trees directly with the object model and typed style values.
• Document Controllers - Code-behind functionality with outlets and actions

Core Engine Configuration

Applies to all documents within the application or process.

• Configuration Files - JSON-based application configuration file (such as scrybersettings.json) with sections for.
  • Namespace Registration - Mapping XML namespaces to .NET assemblies
  • Image Factories - Custom image loading from databases, APIs, or other sources
  • Font Configuration - Registering custom fonts and managing font loading
  • Expression Options - Custom expression functions and operator registration
  • Logging Extensions - Custom trace log sinks

Extension Mechanisms

Applies to any number of applications or processes

• Custom Components - Creating reusable PDF components with custom namespaces

Putting it all together

• Complete Integration Example - All extension mechanisms working together

Further Reading

• Library Architecture - An overview of the libraries, important namespaces and class hierarchies, and the strategies used for parsing; layout; and rendering.
• Best Practices - Guidelines, troubleshooting, and performance considerations

Quick Start

Basic Configuration

{
  "Scryber": {
    "Parsing": {
      "Namespaces": [ /* Custom component namespaces */ ]
    },
    "Fonts": {
      "Register": [ /* Custom fonts */ ]
    },
    "Imaging": {
      "Factories": [ /* Custom image loaders */ ]
    }
  }
}

Using Processing Instructions

<?xml version='1.0' encoding='utf-8' ?>
<?paperwork parser-mode='Strict' 
          log-level='Warnings'
          controller='MyNamespace.MyController, MyAssembly' ?>
<html xmlns='http://www.w3.org/1999/xhtml'>
    <!-- Document content -->
</html>

Creating a Controller

public class MyController
{
    [PDFOutlet(Required = true)]
    public Label TitleLabel { get; set; }
    
    public void Init(InitContext context)
    {
        TitleLabel.Text = "Generated at " + DateTime.Now;
    }
}

Initializing the configuration

The engine options are read from the "Scryber" section of the configuration. Pass the configuration to the engine once at startup, before any documents are generated.

using Microsoft.Extensions.Configuration;

IConfigurationRoot config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

Scryber.ServiceProvider.Init(config);

In ASP.NET Core, builder.Services.AddPaperwork(builder.Configuration); registers the factory and passes the configuration to the engine. See Configuration Structure for the sections and values.

Extension Points Summary

Architecture Principles

1. Dependency Injection - Configuration via IScryberConfigurationService
2. Lazy Loading - Types, assemblies, fonts loaded on-demand
3. Caching - Reflected definitions cached for performance
4. Thread Safety - Configuration access protected with locks
5. Convention over Configuration - Sensible defaults, explicit overrides

Next Steps

• Start with Processing Instructions for document-level configuration
• Learn Document Controllers for code-behind functionality
• Create Custom Components for reusable elements
• See the Complete Integration Example for everything working together

Documentation Version: 1.0
Last Updated: February 2026
Target: Paperwork.Core 9.x

Table of contents