PDF Generation & Chromium Setup

ScreamCode.Reporting uses Playwright with Chromium to generate high-fidelity PDF reports. This guide covers installation, configuration, and troubleshooting.

How it works

When a PDF report is generated, the application:

1. Renders the report as HTML using the configured template
2. Launches a headless Chromium browser via Playwright
3. Renders the HTML and exports it as PDF
4. Optionally applies watermark, QR code, or digital signature

Automatic setup (recommended)

Starting from v1.1.3, the Playwright driver is automatically copied to your publish folder when you build or publish the project. No manual steps required in most cases.

When your app starts, it automatically installs Chromium if not already present. You will see this in the logs:

[ScreamCode.Reporting] Chromium not found. Installing...
[ScreamCode.Reporting] Chromium installed successfully.

Manual Chromium installation

If automatic installation fails, run this command from your application's publish folder:

Windows:

$env:NODE_SKIP_PLATFORM_CHECK = "1"
powershell -ExecutionPolicy Bypass -File playwright.ps1 install chromium

Linux:

./playwright.sh install chromium

Windows Server 2016 compatibility

Windows Server 2016 requires an older Chromium build. The current NuGet package ships with Playwright 1.20.0 which uses chromium-978106 — compatible with Windows Server 2016.

Manual installation on Windows Server 2016

# Step 1: Install Chromium
$env:NODE_SKIP_PLATFORM_CHECK = "1"
powershell -ExecutionPolicy Bypass -File playwright.ps1 install chromium

# Step 2: Copy to system profile (required for IIS)
$src = "$env:LOCALAPPDATA\ms-playwright\chromium-978106"
$dst = "C:\Windows\system32\config\systemprofile\AppData\Local\ms-playwright\chromium-978106"
New-Item -ItemType Directory -Path $dst -Force
Copy-Item -Path $src -Destination $dst -Recurse -Force

Set explicit browser path in appsettings.json

"Pdf": {
    "BrowserExecutablePath": "C:\\Windows\\system32\\config\\systemprofile\\AppData\\Local\\ms-playwright\\chromium-978106\\chrome-win\\chrome.exe"
}

IIS deployment

When running under IIS, the application pool identity needs access to the Chromium browser. The application automatically tries to copy Chromium to the system profile on startup.

If PDF generation fails under IIS, run this PowerShell script as Administrator:

# Grant IIS App Pool access
$acl = Get-Acl "C:\Windows\system32\config\systemprofile\AppData\Local\ms-playwright"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
    "IIS_IUSRS", "FullControl", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\Windows\system32\config\systemprofile\AppData\Local\ms-playwright" $acl

Configuration options

In appsettings.json:

"ScreamReporting": {
    "Pdf": {
        "BrowserExecutablePath": null,
        "DefaultOrientation": "Portrait",
        "TimeoutMs": 30000
    }
}

Digital signature

ScreamCode.Reporting supports visual digital signatures on PDF reports (Enterprise tier).

What is included

A visible signature block is added to the PDF containing:

• Signer name (from certificate)
• Date and time
• Reason for signing

Configuration

"ScreamReporting": {
    "DigitalSignature": {
        "Enabled": true,
        "CertificatePath": "C:\\certs\\my-certificate.pfx",
        "CertificatePassword": "my-password",
        "Reason": "Approved by finance department",
        "VisibleSignature": true,
        "SignaturePage": "Last"
    }
}

Generating a self-signed certificate (for testing)

# Windows PowerShell
$cert = New-SelfSignedCertificate `
    -Subject "CN=My Company, O=My Company Ltd" `
    -CertStoreLocation "Cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -NotAfter (Get-Date).AddYears(5)

Export-PfxCertificate `
    -Cert $cert `
    -FilePath "C:\certs\my-certificate.pfx" `
    -Password (ConvertTo-SecureString -String "my-password" -Force -AsPlainText)

Important notes

Note: The current implementation adds a visual signature block to the PDF. This is a graphical element that shows who signed the document and when. It is NOT a cryptographic PDF signature that can be verified by Adobe Acrobat or other PDF readers as a mathematically valid signature.

>

Cryptographically verifiable PDF signatures (PDF/A, PAdES) are planned for a future release.

Storing certificate password securely

Instead of plain text password in appsettings.json, use environment variables:

"CertificatePassword": "env:PDF_CERT_PASSWORD"

Then set the environment variable on your server:

[System.Environment]::SetEnvironmentVariable("PDF_CERT_PASSWORD", "my-password", "Machine")

Troubleshooting

PDF generation fails with "Process exited"

Playwright driver not found or incompatible Node.js. Solution: ensure the .playwright folder exists in your application's root directory. It should be copied automatically on build/publish.

PDF generation fails with "Executable doesn't exist"

Chromium not installed. Run the manual installation command above.

PDF generation fails under IIS but works locally

IIS App Pool identity doesn't have access to Chromium. Run the IIS permissions script above.

Timeout errors

Increase TimeoutMs in configuration:

"Pdf": {
    "TimeoutMs": 60000
}

Windows Server 2016 — "not a valid application for this OS platform"

You have a newer Chromium installed that is not compatible with Windows Server 2016. Follow the Windows Server 2016 manual installation steps above to install chromium-978106.