From 945706bab40c3c828b5ce2c4eec314e4333e7357 Mon Sep 17 00:00:00 2001 From: Jaben Cargman Date: Sun, 5 Oct 2025 13:51:46 -0400 Subject: [PATCH] Improve and update README with current API examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added Required Using Statements section for easier setup - Added new feature examples for v2.6+ through v2.8.1+: * Cookie support for authenticated requests (v2.8.1) * SinglePage property for single-page PDF output (v2.8.1) * Document metadata support (v2.6) * PDF format conversion examples - Added Advanced Features section with: * PDF/UA support for HTML and PDF conversions (v2.4+) * Flatten PDFs (v2.8+) * Skip Network Idle Event (Gotenberg v8+) * Custom Page Properties reference - Updated Office merge example to include PDF format setting - Fixed enum references (PdfFormats → LibrePdfFormats) - Added version tags to examples for clarity All examples now reflect current v2.8.1+ API patterns. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 188 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 62283ce..d854b86 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,15 @@ public void ConfigureServices(IServiceCollection services) ``` # Using GotenbergSharpClient -*See the [linqPad folder](linqpad/)* for complete examples. +*See the [linqPad folder](linqpad/)* for complete examples. + +## Required Using Statements +```csharp +using Gotenberg.Sharp.API.Client; +using Gotenberg.Sharp.API.Client.Domain.Builders; +using Gotenberg.Sharp.API.Client.Domain.Builders.Faceted; +using Gotenberg.Sharp.API.Client.Domain.Requests.Facets; // For Cookie, etc. +``` ### Html To Pdf *With embedded assets:* @@ -139,13 +147,14 @@ public async Task CreateFromUrl(string headerPath, string footerPath) } ``` ## Merge Office Docs -*Merges office documents and configures the request time-out:* +*Merges office documents:* ```csharp public async Task DoOfficeMerge(string sourceDirectory) { var builder = new MergeOfficeBuilder() - .WithAsyncAssets(async a => a.AddItems(await GetDocsAsync(sourceDirectory))); + .WithAsyncAssets(async a => a.AddItems(await GetDocsAsync(sourceDirectory))) + .SetPdfFormat(LibrePdfFormats.A2b); var request = await builder.BuildAsync(); return await _sharpClient.MergeOfficeDocsAsync(request); @@ -174,6 +183,92 @@ public async Task CreateFromMarkdown() return await _sharpClient.HtmlToPdfAsync(request); } ``` +### Working with Cookies +*Add cookies to the Chromium cookie jar for authenticated requests (v2.8.1+):* + +```csharp +public async Task CreatePdfWithCookies() +{ + var builder = new UrlRequestBuilder() + .SetUrl("https://example.com/protected") + .SetConversionBehaviors(b => + { + b.AddCookie(new Cookie + { + Name = "session_token", + Value = "abc123xyz", + Domain = "example.com", + Path = "/", + Secure = true, + HttpOnly = true, + SameSite = "Lax" + }); + }) + .WithPageProperties(pp => pp.UseChromeDefaults()); + + var request = await builder.BuildAsync(); + return await _sharpClient.UrlToPdfAsync(request); +} +``` + +### Document Metadata +*Add custom metadata to your PDFs (v2.6+):* + +```csharp +public async Task CreatePdfWithMetadata() +{ + var builder = new HtmlRequestBuilder() + .AddDocument(doc => doc.SetBody("

Document with Metadata

")) + .SetConversionBehaviors(b => + { + b.SetMetadata(new Dictionary + { + { "Author", "John Doe" }, + { "Title", "My Document" }, + { "Subject", "Important Report" }, + { "Keywords", "report, pdf, gotenberg" } + }); + }) + .WithPageProperties(pp => pp.UseChromeDefaults()); + + var request = await builder.BuildAsync(); + return await _sharpClient.HtmlToPdfAsync(request); +} +``` + +### PDF Format Conversion +*Convert PDFs to PDF/A formats (v2.8+):* + +```csharp +public async Task ConvertToPdfA(string pdfPath) +{ + var builder = new PdfConversionBuilder() + .WithPdfs(b => b.AddItem("document.pdf", File.ReadAllBytes(pdfPath))) + .SetPdfFormat(LibrePdfFormats.A2b); + + var request = await builder.BuildAsync(); + return await _sharpClient.ConvertPdfDocumentsAsync(request); +} +``` + +### Single Page Output +*Generate a single-page PDF from multi-page content (v2.8.1+):* + +```csharp +public async Task CreateSinglePagePdf() +{ + var builder = new UrlRequestBuilder() + .SetUrl("https://www.example.com") + .WithPageProperties(pp => + { + pp.UseChromeDefaults() + .SetSinglePage(true); + }); + + var request = await builder.BuildAsync(); + return await _sharpClient.UrlToPdfAsync(request); +} +``` ### Webhook *All request types support webhooks* @@ -272,4 +367,93 @@ async Task ExecuteRequestsAndMerge(IEnumerable requests) var request = mergeBuilder.Build(); return await _sharpClient.MergePdfsAsync(request); } -``` +``` + +## Advanced Features + +### PDF/UA Support for HTML Conversions +*Enable Universal Access for accessible PDFs from HTML (v2.4+):* + +```csharp +public async Task CreateAccessiblePdf() +{ + var builder = new HtmlRequestBuilder() + .AddDocument(doc => doc.SetBody("

Accessible Document

")) + .SetConversionBehaviors(b => b.SetPdfUa(true)) + .WithPageProperties(pp => pp.UseChromeDefaults()); + + var request = await builder.BuildAsync(); + return await _sharpClient.HtmlToPdfAsync(request); +} +``` + +### PDF/UA for PDF Conversions +*Enable Universal Access when converting PDFs to PDF/A (v2.4+):* + +```csharp +public async Task ConvertToAccessiblePdfA(string pdfPath) +{ + var builder = new PdfConversionBuilder() + .WithPdfs(b => b.AddItem("document.pdf", File.ReadAllBytes(pdfPath))) + .SetPdfFormat(LibrePdfFormats.A2b) + .EnablePdfUa(true); + + var request = await builder.BuildAsync(); + return await _sharpClient.ConvertPdfDocumentsAsync(request); +} +``` + +### Flatten PDFs +*Flatten PDF forms and annotations (v2.8+):* + +```csharp +public async Task FlattenPdf(string pdfPath) +{ + var builder = new PdfConversionBuilder() + .WithPdfs(b => b.AddItem("form.pdf", File.ReadAllBytes(pdfPath))) + .EnableFlatten(true); + + var request = await builder.BuildAsync(); + return await _sharpClient.ConvertPdfDocumentsAsync(request); +} +``` + +### Skip Network Idle Event +*Speed up conversions by skipping network idle wait (Gotenberg v8+ only):* + +```csharp +public async Task FastConversion() +{ + var builder = new UrlRequestBuilder() + .SetUrl("https://example.com") + .SetConversionBehaviors(b => b.SkipNetworkIdleEvent()) + .WithPageProperties(pp => pp.UseChromeDefaults()); + + var request = await builder.BuildAsync(); + return await _sharpClient.UrlToPdfAsync(request); +} +``` + +### Custom Page Properties +*Fine-tune page dimensions and properties:* + +```csharp +public async Task CustomPageProperties() +{ + var builder = new HtmlRequestBuilder() + .AddDocument(doc => doc.SetBody("

Custom Page

")) + .WithPageProperties(pp => + { + pp.SetPaperSize(PaperSizes.Letter) + .SetMargins(Margins.Normal) + .SetScale(0.95) + .SetLandscape() + .SetPrintBackground(true) + .SetGenerateDocumentOutline(true) + .SetOmitBackground(false); + }); + + var request = await builder.BuildAsync(); + return await _sharpClient.HtmlToPdfAsync(request); +} +```