Rmp.DocProc.HtmlToPdf 1.0.1

Rmp.DocProc.HtmlToPdf

Async-friendly document formatting package, designed for queued jobs.

Current capability

• HTML file to PDF file conversion using Playwright Chromium.
• HTML file to PNG file conversion (scaffold for additional output formats).
• Optional relative URL normalization to absolute URLs with a provided base URL.

Install

dotnet add package Rmp.DocProc.HtmlToPdf

Browser provisioning (no manual install required by default)

The package tries to auto-install a Playwright browser at runtime if Chromium is missing.

• Default behavior: first run downloads Chromium automatically.
• Good for worker services where you want install-free onboarding.
• Requires network access on first run.

You can still preinstall manually if preferred:

pwsh bin/Debug/net8.0/playwright.ps1 install chromium

or for published artifacts:

pwsh playwright.ps1 install chromium

Important limitation:

• NuGet cannot practically bundle all OS-specific browser binaries inside a single package without major size and distribution drawbacks.
• The closest "bundled" experience is auto-provisioning on first run, or reusing an already installed browser executable/channel.

Usage (queued worker)

using Rmp.DocProc.HtmlToPdf.Abstractions;
using Rmp.DocProc.HtmlToPdf.Html;
using Rmp.DocProc.HtmlToPdf.Pipeline;

var handler = new HtmlToPdfConversionHandler(new HtmlToPdfOptions
{
    BaseUrl = "https://example.com",
    NormalizeRelativeUrls = true,
    PrintBackground = true,
    AutoInstallBrowser = true
});

var dispatcher = new ConversionDispatcher(new[] { handler });

var job = new ConversionJob(
    SourcePath: "C:/queue/input/123.html",
    DestinationPath: "C:/queue/output/123.pdf",
    InputFormat: DocumentFormat.Html,
    OutputFormat: DocumentFormat.Pdf,
    Metadata: new Dictionary<string, string>
    {
        ["jobId"] = "123"
    });

await dispatcher.DispatchAsync(job);

Use system Chrome or Edge instead of Playwright-managed Chromium

If your environment already has a managed browser installation, point the handler to it:

var handler = new HtmlToPdfConversionHandler(new HtmlToPdfOptions
{
    AutoInstallBrowser = false,
    BrowserChannel = "msedge"
    // or BrowserExecutablePath = "C:/Program Files/Google/Chrome/Application/chrome.exe"
});

Usage with DI and background worker

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Rmp.DocProc.HtmlToPdf.DependencyInjection;
using Rmp.DocProc.HtmlToPdf.Html;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services
            .AddRubiconDocProcHtmlToPdf(
                pdfOptions: new HtmlToPdfOptions
                {
                    BaseUrl = "https://example.com/assets/",
                    NormalizeRelativeUrls = true
                },
                imageOptions: new HtmlToImageOptions
                {
                    Width = 1280,
                    Height = 1810
                })
            .AddRubiconDocProcBackgroundWorker(queueCapacity: 500);
    })
    .Build();

await host.RunAsync();

Queue producer code can enqueue ConversionJob values through IConversionJobQueue.

Migrating from legacy EO PDF background jobs

The old PdfDocumentBackgroundGenerationJob mixed queue lifecycle management, HTML normalization, PDF generation, and DB writeback in one class.

With Rmp.DocProc.HtmlToPdf, split responsibilities:

• Keep your existing backlog selection/status transitions in your app layer.
• Use HtmlToPdfConversionHandler only for HTML → PDF conversion.
• Keep destination persistence (for example CCMBinaryData.Data) in your app layer.

Recommended mapping:

• Old EO.Pdf bootstrap/shutdown: remove.
• Old ParentSitePdfWriter.MakePdf(...) / AdminSitePdfWriter.GeneratePDF(...): replace with HtmlToPdfConversionHandler.HandleAsync(...).
• Old string replacement for absolute URLs: replace with HtmlUrlNormalizer.NormalizeAsync(...) (or handler-level normalization via options).
• Old queue error/status fields: keep exactly as-is in your own processing loop.

Example migration pattern (pseudo-realistic app code):

public async Task ProcessPdfBacklogAsync(BackgroundQueue backlog, CancellationToken ct)
{
    backlog.ProcessingAttempts++;
    backlog.ProcessingDate = DateTimeOffset.UtcNow;
    await _db.SaveChangesAsync(ct);

    PdfDocumentParameters parameters;
    try
    {
        parameters = JsonConvert.DeserializeObject<PdfDocumentParameters>(backlog.DataJSON)
            ?? throw new InvalidOperationException("DataJSON was null.");
    }
    catch (Exception ex)
    {
        await MarkErrorAsync(backlog, "Failed to parse parameters.", ex, ct);
        return;
    }

    try
    {
        var handler = new HtmlToPdfConversionHandler(new HtmlToPdfOptions
        {
            // BaseUrl can stay null here and be supplied per-conversion below.
            BaseUrl = null,
            NormalizeRelativeUrls = true,
            PrintBackground = true,
            // For locked-down hosts use enterprise settings instead:
            // AutoInstallBrowser = false,
            // BrowserChannel = "msedge"
        });

        var pdfBytes = await handler.ConvertHtmlToPdfAsync(
            parameters.HtmlInput,
            baseUrl: parameters.BaseUrl,
            cancellationToken: ct);

        // Your old destination behavior stays in your application code.
        var record = await _db.CCMBinaryDatas.SingleAsync(o => o.ID == parameters.Destination.RecordID, ct);
        record.Data = pdfBytes;

        backlog.ProcessedDate = DateTimeOffset.UtcNow;
        backlog.Status = (int)BackgroundQueue_Status.Processed;
        backlog.Exception = null;
        backlog.FailuresJSON = null;

        await _db.SaveChangesAsync(ct);
    }
    catch (Exception ex)
    {
        await MarkErrorAsync(backlog, "Failed to generate/save PDF.", ex, ct);
    }
}

Why this preserves legacy behavior:

• Attempts/status transitions remain under your existing DB transaction model.
• The converter is now isolated and testable.
• EO runtime/log lifecycle is removed and replaced by Playwright browser lifecycle per conversion.
• URL normalization is deterministic and explicit.

Strict enterprise mode (no runtime downloads)

Use strict mode when hosts are locked down and browser binaries must be provisioned by ops.

using Rmp.DocProc.HtmlToPdf.DependencyInjection;

services
    .AddRubiconDocProcHtmlToPdfEnterprise(
        pdfOptions: new HtmlToPdfOptions
        {
            BrowserChannel = "msedge"
        },
        imageOptions: new HtmlToImageOptions
        {
            BrowserChannel = "msedge"
        },
        preflightBrowserOnStartup: true)
    .AddRubiconDocProcBackgroundWorker();

What strict mode does:

• Forces AutoInstallBrowser = false for registered handlers.
• Optionally preflights browser launch at host startup.
• Throws a clear error if no runnable browser is available.

Relative URL handling

When BaseUrl is set and NormalizeRelativeUrls is true:

• <base href="..."> is injected/updated in <head>.
• relative values in src, href, poster, data, and srcset are rewritten to absolute URLs.

This supports the flow where a pre-rendered HTML file is queued and converted later.

Pre-queue normalization

If your producer service needs to rewrite relative URLs before the HTML is saved and queued, call HtmlUrlNormalizer.NormalizeAsync(...) directly and persist the returned HTML.

using Rmp.DocProc.HtmlToPdf.Html;

var normalizedHtml = await HtmlUrlNormalizer.NormalizeAsync(rawHtml, "https://example.com/base/");
await File.WriteAllTextAsync("C:/queue/input/123.html", normalizedHtml);