Skip to content

Improve and update README with current API examples #64

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 5, 2025
Merged

Improve and update README with current API examples #64

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 188 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:*
Expand Down Expand Up @@ -139,13 +147,14 @@ public async Task<Stream> CreateFromUrl(string headerPath, string footerPath)
}
```
## Merge Office Docs
*Merges office documents and configures the request time-out:*
*Merges office documents:*

```csharp
public async Task<Stream> 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);
Expand Down Expand Up @@ -174,6 +183,92 @@ public async Task<Stream> 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<Stream> 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<Stream> CreatePdfWithMetadata()
{
var builder = new HtmlRequestBuilder()
.AddDocument(doc => doc.SetBody("<html><body><h1>Document with Metadata</h1></body></html>"))
.SetConversionBehaviors(b =>
{
b.SetMetadata(new Dictionary<string, object>
{
{ "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<Stream> 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<Stream> 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*

Expand Down Expand Up @@ -272,4 +367,93 @@ async Task<Stream> ExecuteRequestsAndMerge(IEnumerable<UrlRequest> 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<Stream> CreateAccessiblePdf()
{
var builder = new HtmlRequestBuilder()
.AddDocument(doc => doc.SetBody("<html><body><h1>Accessible Document</h1></body></html>"))
.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<Stream> 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<Stream> 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<Stream> 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<Stream> CustomPageProperties()
{
var builder = new HtmlRequestBuilder()
.AddDocument(doc => doc.SetBody("<html><body><h1>Custom Page</h1></body></html>"))
.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);
}
```
Loading