BSynchro.Printout.Public
8.1.1
dotnet add package BSynchro.Printout.Public --version 8.1.1
NuGet\Install-Package BSynchro.Printout.Public -Version 8.1.1
<PackageReference Include="BSynchro.Printout.Public" Version="8.1.1" />
<PackageVersion Include="BSynchro.Printout.Public" Version="8.1.1" />
<PackageReference Include="BSynchro.Printout.Public" />
paket add BSynchro.Printout.Public --version 8.1.1
#r "nuget: BSynchro.Printout.Public, 8.1.1"
#:package BSynchro.Printout.Public@8.1.1
#addin nuget:?package=BSynchro.Printout.Public&version=8.1.1
#tool nuget:?package=BSynchro.Printout.Public&version=8.1.1
BSynchro.Printout.Public
Html-to-pdf printouts for ASP.NET Core (net8.0). A host service references this package and keeps its own Razor
templates under wwwroot; the package renders a template with the posted model and returns a pdf.
Two pdf engines:
| Engine | Endpoint | Needs on the server |
|---|---|---|
| wkhtmltopdf (default) | POST api/Printout/GeneratePrintout |
nothing (native library embedded, Windows) |
| Chromium (Playwright, opt-in) | POST api/Printout/GeneratePlaywrightPrintout |
the Playwright driver in the output + Chromium installed once per server |
Getting started
using BSynchro.Printout.Public;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddPrintOut();
var app = builder.Build();
app.UsePrintOut(); // CORS (any origin/header/method) + MVC
app.Run();
Templates go under wwwroot; the request's TemplateFolder is an absolute path or a path relative to wwwroot
(e.g. printouts\MyDocument). Images, stylesheets and fonts are resolved relative to the template folder.
Endpoints
| Method | Route | Description |
|---|---|---|
| POST | api/Printout/GeneratePrintout |
wkhtmltopdf engine, returns application/pdf |
| POST | api/Printout/GeneratePrintoutEncrypted |
same, JWE-encrypted request body; needs services.AddHttpJoseSecurityEncryption(configuration) |
| POST | api/Printout/GeneratePlaywrightPrintout |
Chromium engine |
| GET | api/Printout/Health |
converts a tiny pdf through the wkhtmltopdf queue; 200, or 503 with the queue state after Printout:HealthCheckTimeoutSeconds |
| GET | api/Printout/PlaywrightHealth |
launches Chromium if needed and renders a tiny pdf; 200, or 503 |
| GET | api/Printout/justdoit |
liveness only, returns hello (does not touch the pdf engines) |
Point monitoring / recycle scripts at the health endpoints, not at a liveness endpoint.
Request body
{
"Title": "My document", // document title and file name (Title.pdf)
"LanguageId": 1,
"Model": { }, // anything: the templates read it as Model.Model
"TemplateFolder": "printouts\\MyDocument",
"BodyTemplateFileName": "BodyTemplate.cshtml",
"HeaderTemplateFileName": "HeaderTemplate.cshtml", // optional
"FooterTemplateFileName": "FooterTemplate.cshtml", // optional
"Options": { "web.enableIntelligentShrinking": "false" }, // optional, raw converter options
"MarginOptions": { // optional, both engines
"PaperSize": "A4",
"Orientation": "Portrait", // Portrait | Landscape
"TopMargin": "28.0", "BottomMargin": "22.0", "LeftMargin": "4.0", "RightMargin": "5.0"
},
"ObjectOptions": { // optional, wkhtmltopdf only
"HeaderSpacing": "10.0", "FooterSpacing": "10.0"
}
}
Settings
| Setting | Default | Effect |
|---|---|---|
Printout:HealthCheckTimeoutSeconds |
90 |
health endpoints answer 503 when the test pdf is not back in time |
Printout:SlowConversionSeconds |
60 |
a printout slower than this (wait + conversion) is logged as a Warning |
EnableDefualtFooter |
false |
adds "Page [page] of [toPage]" at the bottom right (historical spelling) |
AppSettings:DeleteTempFolderWhenDoneWithPrintout |
true |
deletes the temporary html files after each printout |
Playwright:MaxConcurrentPages |
4 |
Chromium pages converted at the same time |
Playwright:ConversionTimeoutSeconds |
60 |
per Chromium conversion |
ConverterGlobalOptions / ConverterObjectOptions (DI singletons) |
spacing 10.0 |
service-wide wkhtmltopdf options, used when the request has none |
Logging
Categories: BSynchro.Printout.Converter (wkhtmltopdf queue), BSynchro.PrintoutsRuntime.PdfConversion.PlaywrightPdfConverter
(Chromium), BSynchro.Printout.Public.*Controller (requests, health).
- wkhtmltopdf: a start line before the native call, an end line with the queue wait and the conversion time, and a
Warning every 15 s while a conversion runs past
SlowConversionSeconds(with the process CPU and memory). - Chromium: the wait for a free page and the render time.
- A request whose caller disconnected before its turn is skipped and logged.
Keep BSynchro.Printout* at Information, and write it to a non-buffered target so the last line before a crash is kept.
wkhtmltopdf: what to know
All wkhtmltopdf conversions of a process run one at a time on one thread (the library requires it). wkhtmltopdf keeps
native memory after large documents; after many large conversions it can stop responding or end the process, and a
restart clears it. Monitor api/Printout/Health and recycle on 503; a memory-based recycle limit on the host
avoids reaching that state.
Chromium engine (opt-in)
csproj: copy the Playwright driver to the build and publish output:
<PropertyGroup> <PrintoutChromiumEngine>true</PrintoutChromiumEngine> </PropertyGroup>Optional, Program.cs: launch Chromium at startup so the first printout does not wait for it:
builder.Services.AddPlaywrightWarmUp();Install Chromium once per server (from the published service folder):
.\.playwright\node\win32_x64\node.exe .\.playwright\package\cli.js install chromium, and give the app pool identity read access to the browsers folder (PLAYWRIGHT_BROWSERS_PATH).Check:
GET api/Printout/PlaywrightHealthreturns 200.
Without the opt-in, GeneratePlaywrightPrintout fails (500) and PlaywrightHealth returns 503; the wkhtmltopdf
endpoints work as usual.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net8.0
- Bsynchro.Security (>= 8.0.4)
- Microsoft.AspNetCore.Mvc.NewtonsoftJson (>= 8.0.16)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
- Microsoft.Playwright (>= 1.52.0)
- Newtonsoft.Json (>= 13.0.3)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.