### Minimal Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

A basic example demonstrating how to convert an HTML string to a PDF document.

```csharp
using WkHtmlToPdfDotNet;

var converter = new BasicConverter(new PdfTools());
var doc = new HtmlToPdfDocument()
{
    Objects = {
        new ObjectSettings() { HtmlContent = "<h1>Hello</h1>" }
    }
};
byte[] pdf = converter.Convert(doc);
```

--------------------------------

### Installation

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Install the wkhtmltopdf-dotnet package using the .NET CLI.

```bash
dotnet add package Haukcode.WkHtmlToPdfDotNet
```

--------------------------------

### ASP.NET Core Setup

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Shows how to set up the wkhtmltopdf-dotnet converter in an ASP.NET Core application and create a controller to generate PDFs from HTML content.

```csharp
// In Startup.cs or Program.cs
services.AddSingleton<IConverter>(
    new SynchronizedConverter(new PdfTools())
);

// In your controller
[ApiController]
public class PdfController : ControllerBase
{
    private readonly IConverter converter;
    
    public PdfController(IConverter converter)
    {
        this.converter = converter;
    }
    
    [HttpPost("generate")]
    public IActionResult Generate([FromBody] string html)
    {
        var doc = new HtmlToPdfDocument()
        {
            Objects = { new ObjectSettings() { HtmlContent = html } }
        };
        
        byte[] pdf = converter.Convert(doc);
        return File(pdf, "application/pdf");
    }
}
```

--------------------------------

### Complete Example: Report

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Demonstrates how to create a PDF report with a cover, table of contents, and content from a URL, including headers and footers.

```csharp
var doc = new HtmlToPdfDocument()
{
    GlobalSettings = new GlobalSettings()
    {
        ColorMode = ColorMode.Color,
        Orientation = Orientation.Portrait,
        PaperSize = PaperKind.A4,
        Margins = new MarginSettings(25, 25, 25, 25),
        DPI = 300
    }
};

doc.Objects.Add(new CoverSettings()
{
    HtmlContent = "<h1>Report 2024</h1>"
});

doc.Objects.Add(new TableOfContentsSettings()
{
    CaptionText = "Contents"
});

doc.Objects.Add(new ObjectSettings()
{
    Page = "https://example.com/report",
    HeaderSettings = new HeaderSettings()
    {
        Right = "Page [page]",
        Line = true
    },
    FooterSettings = new FooterSettings()
    {
        Center = "[date]",
        Line = true
    }
});

byte[] pdf = converter.Convert(doc);
System.IO.File.WriteAllBytes("report.pdf", pdf);
```

--------------------------------

### LoadSettings Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

An example of how to instantiate and configure LoadSettings.

```csharp
var loadSettings = new LoadSettings()
{
    Username = "user",
    Password = "pass",
    JSDelay = 2000,
    ZoomFactor = 1.5,
    CustomHeaders = new Dictionary<string, string>()
    {
        { "Authorization", "Bearer token" }
    },
    Cookies = new Dictionary<string, string>()
    {
        { "sessionid", "abc123" }
    }
};
```

--------------------------------

### WebSettings Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

An example of how to instantiate and configure WebSettings.

```csharp
var webSettings = new WebSettings()
{
    Background = true,
    LoadImages = true,
    EnableJavascript = true,
    DefaultEncoding = "utf-8",
    PrintMediaType = true
};
```

--------------------------------

### CoverSettings Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

Example of how to create and configure CoverSettings.

```csharp
var cover = new CoverSettings()
{
    HtmlContent = "<h1>Cover Page</h1><p>My Document</p>",
    IsCover = true
};
```

--------------------------------

### FooterSettings Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

An example of how to instantiate and configure FooterSettings.

```csharp
var footerSettings = new FooterSettings()
{
    FontSize = 9,
    Center = "© 2024 Company Name",
    Line = true
};
```

--------------------------------

### Page Numbering Placeholders

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Example usage of page numbering placeholders in header and footer settings.

```csharp
headerSettings.Right = "Page [page] of [toPage]";
footerSettings.Center = "[date]";
```

--------------------------------

### MarginSettings Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

Example of how to configure MarginSettings.

```csharp
var margins = new MarginSettings()
{
    Unit = Unit.Millimeters,
    Top = 20,
    Right = 15,
    Bottom = 20,
    Left = 15
};
```

--------------------------------

### HeaderSettings Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

An example of how to instantiate and configure HeaderSettings.

```csharp
var headerSettings = new HeaderSettings()
{
    FontSize = 10,
    FontName = "Arial",
    Line = true,
    Right = "Page [page] of [toPage]",
    Spacing = 2.5
};
```

--------------------------------

### Install Package

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/wiki/Home

Install the WkHtmlToPdf-DotNet library through Nuget using the Package Manager Console.

```powershell
PM> Install-Package WkHtmlToPdf-DotNet
```

--------------------------------

### Complete Configuration Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

A comprehensive example demonstrating the configuration of GlobalSettings, CoverSettings, TableOfContentsSettings, ObjectSettings, WebSettings, HeaderSettings, FooterSettings, LoadSettings, and the conversion process.

```csharp
var document = new HtmlToPdfDocument()
{
    GlobalSettings = new GlobalSettings()
    {
        ColorMode = ColorMode.Color,
        Orientation = Orientation.Portrait,
        PaperSize = PaperKind.A4,
        Margins = new MarginSettings(25, 25, 25, 25),
        DPI = 300,
        ImageDPI = 600,
        ImageQuality = 95,
        UseCompression = true,
        Outline = true,
        OutlineDepth = 3,
        DocumentTitle = "Financial Report Q4 2024"
    },
    Objects = {
        // Cover page
        new CoverSettings()
        {
            HtmlContent = "<h1>Financial Report</h1><p>Q4 2024</p>",
            IsCover = true
        },
        
        // Table of contents
        new TableOfContentsSettings()
        {
            CaptionText = "Contents",
            UseDottedLines = true
        },
        
        // Content page
        new ObjectSettings()
        {
            Page = "https://example.com/report",
            WebSettings = new WebSettings()
            {
                Background = true,
                LoadImages = true,
                EnableJavascript = true,
                PrintMediaType = true,
                DefaultEncoding = "utf-8"
            },
            HeaderSettings = new HeaderSettings()
            {
                FontName = "Arial",
                FontSize = 10,
                Line = true,
                Left = "Company Name",
                Right = "Page [page]",
                Spacing = 2.5
            },
            FooterSettings = new FooterSettings()
            {
                FontSize = 9,
                Line = true,
                Center = "© 2024 Company Name",
                Right = "[date]"
            },
            LoadSettings = new LoadSettings()
            {
                JSDelay = 2000,
                Username = "report_user",
                Password = "password",
                CustomHeaders = new Dictionary<string, string>()
                {
                    { "Authorization", "Bearer token123" }
                }
            }
        }
    }
};

var converter = new SynchronizedConverter(new PdfTools());
byte[] pdf = converter.Convert(document);
```

--------------------------------

### Usage Example: Orientation

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

Example of setting the Orientation in GlobalSettings.

```csharp
globalSettings.Orientation = Orientation.Landscape;
```

--------------------------------

### Network and Headers Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Sets up a proxy, custom HTTP headers, and whether to repeat them.

```csharp
loadSettings.Proxy = "http://proxy.example.com:8080";

loadSettings.CustomHeaders = new Dictionary<string, string>()
{
    { "Authorization", "Bearer token" },
    { "User-Agent", "MyApp/1.0" }
};

loadSettings.RepeatCustomHeaders = true;  // Send to all resources
```

--------------------------------

### TableOfContentsSettings Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

Example of how to create and configure TableOfContentsSettings.

```csharp
var toc = new TableOfContentsSettings()
{
    IsTableOfContent = true,
    CaptionText = "Table of Contents",
    UseDottedLines = true
};
```

--------------------------------

### Install via Package Manager Console

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/NuGetInfo.md

Command to install the library using the Package Manager Console in Visual Studio.

```powershell
PM> Install-Package Haukcode.WkHtmlToPdfDotNet
```

--------------------------------

### Tools Property Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/IConverter.md

Example showing how to access the Tools property of the IConverter interface to check if the library is loaded and get its version.

```csharp
bool isLoaded = converter.Tools.IsLoaded;
string version = converter.Tools.GetLibraryVersion();
```

--------------------------------

### Authentication Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Sets the username and password for authentication when loading resources.

```csharp
loadSettings.Username = "user@example.com";
loadSettings.Password = "secret";
```

--------------------------------

### GlobalSettings Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

Example of how to configure GlobalSettings for PDF generation.

```csharp
var settings = new GlobalSettings()
{
    ColorMode = ColorMode.Color,
    Orientation = Orientation.Portrait,
    PaperSize = PaperKind.A4,
    DPI = 300,
    Margins = new MarginSettings(20, 20, 20, 20),
    DocumentTitle = "My Document",
    UseCompression = true
};
```

--------------------------------

### Resolution and Quality Settings

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Example of setting DPI, ImageDPI, and ImageQuality.

```csharp
globalSettings.DPI = 300;
globalSettings.ImageDPI = 600;
globalSettings.ImageQuality = 94;  // Default: 94
```

--------------------------------

### Margin Units

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Example of setting margins with a specified unit (e.g., Millimeters).

```csharp
var margins = new MarginSettings()
{
    Unit = Unit.Millimeters,   // or Inches, Centimeters
    Top = 20,
    Bottom = 20,
    Left = 15,
    Right = 15
};
```

--------------------------------

### Margin Settings Constructor Shorthand

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Example of initializing MarginSettings using a constructor shorthand.

```csharp
globalSettings.Margins = new MarginSettings(20, 20, 20, 20);  // top, right, bottom, left
```

--------------------------------

### Styling Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Configures the font name and size for headers and footers.

```csharp
headerSettings.FontName = "Arial";
headerSettings.FontSize = 10;
footerSettings.FontSize = 9;
```

--------------------------------

### Usage Example: ColorMode

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

Example of setting the ColorMode in GlobalSettings.

```csharp
globalSettings.ColorMode = ColorMode.Grayscale;
```

--------------------------------

### Usage Example: Unit and Margins

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

Example of setting Unit and margin values in MarginSettings.

```csharp
var margins = new MarginSettings()
{
    Unit = Unit.Inches,
    Top = 1.0,
    Bottom = 1.0
};
```

--------------------------------

### CreateGlobalSettings Method Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/PdfTools.md

Example demonstrating the creation and usage of global settings, including setting an orientation and ensuring the settings object is destroyed.

```csharp
IntPtr globalSettings = tools.CreateGlobalSettings();
try
{
    tools.SetGlobalSetting(globalSettings, "orientation", "Landscape");
    // Use settings...
}
finally
{
    tools.DestroyGlobalSetting(globalSettings);
}
```

--------------------------------

### HtmlToPdfDocument Constructor Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/HtmlToPdfDocument.md

A simple example demonstrating how to instantiate the HtmlToPdfDocument class.

```csharp
var document = new HtmlToPdfDocument();
```

--------------------------------

### ObjectSettings Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

Example of how to configure ObjectSettings for a single HTML object.

```csharp
var settings = new ObjectSettings()
{
    Page = "https://example.com",
    WebSettings = new WebSettings()
    {
        EnableJavascript = true,
        DefaultEncoding = "utf-8"
    },
    HeaderSettings = new HeaderSettings()
    {
        Line = true,
        FontSize = 10,
        Right = "Page [page]"
    }
};
```

--------------------------------

### Layout Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Enables a line below the header or above the footer and sets the spacing.

```csharp
headerSettings.Line = true;      // Draw line below header
headerSettings.Spacing = 2.5;    // 2.5mm spacing below header

footerSettings.Line = true;      // Draw line above footer
footerSettings.Spacing = 2.0;    // 2.0mm spacing above footer
```

--------------------------------

### Docker Installation Steps (Debian-based)

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/README.md

Commands to install necessary libraries and wkhtmltopdf within a Debian-based Linux Docker container for .NET Core.

```bash
RUN apt update
RUN apt install -y libgdiplus
RUN ln -s /usr/lib/libgdiplus.so /lib/x86_64-linux-gnu/libgdiplus.so
RUN apt-get install -y --no-install-recommends zlib1g fontconfig libfreetype6 libx11-6 libxext6 libxrender1 wget gdebi
RUN wget https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox_0.12.5-1.stretch_amd64.deb
RUN gdebi --n wkhtmltox_0.12.5-1.stretch_amd64.deb
RUN apt install libssl1.1
RUN ln -s /usr/local/lib/libwkhtmltox.so /usr/lib/libwkhtmltox.so
```

--------------------------------

### Catch Exceptions

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Demonstrates how to catch specific exceptions that may occur during PDF conversion.

```csharp
try
{
    byte[] pdf = converter.Convert(document);
}
catch (ArgumentException)
{
    // No objects defined
}
catch (NotSupportedException)
{
    // wkhtmltopdf not available
}
catch (AggregateException)
{
    // Background thread error (SynchronizedConverter)
}
```

--------------------------------

### Margin Settings Initialization

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Example of initializing and setting MarginSettings with specific units and values.

```csharp
var margins = new MarginSettings()
{
    Unit = Unit.Millimeters,  // or Inches, Centimeters
    Top = 20,
    Bottom = 20,
    Left = 15,
    Right = 15
};

globalSettings.Margins = margins;
```

--------------------------------

### Compression Setting

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Example of enabling PDF compression.

```csharp
globalSettings.UseCompression = true;
```

--------------------------------

### ExtendedQt Method Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/PdfTools.md

Example demonstrating how to check if the native library was built with extended Qt features.

```csharp
if (tools.ExtendedQt())
{
    Console.WriteLine("Extended Qt features available");
}
```

--------------------------------

### Paper and Orientation

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Set global settings for paper size, orientation, and margins.

```csharp
globalSettings.PaperSize = PaperKind.A4;
globalSettings.Orientation = Orientation.Portrait;
globalSettings.Margins = new MarginSettings(20, 20, 20, 20);
```

--------------------------------

### Cookies and POST Data

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Example of setting cookies and POST data for the load settings.

```csharp
loadSettings.Cookies = new Dictionary<string, string>()
{
    { "sessionid", "abc123" },
    { "user", "john" }
};

loadSettings.Post = new Dictionary<string, string>()
{
    { "action", "print" },
    { "format", "pdf" }
};
```

--------------------------------

### Full Conversion Workflow Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/IConverter.md

This example shows how to create a SynchronizedConverter, register event handlers for phase, progress, error, and warning events, define a PdfDocument with global and object settings, perform the conversion, and dispose of the converter.

```csharp
using System;
using WkHtmlToPdfDotNet;
using WkHtmlToPdfDotNet.EventDefinitions;

// Create converter
var converter = new SynchronizedConverter(new PdfTools());

// Register event handlers
converter.PhaseChanged += (s, e) =>
    Console.WriteLine($"Phase: {e.Description}");

converter.ProgressChanged += (s, e) =>
    Console.WriteLine($"Progress: {e.Description}");

converter.Error += (s, e) =>
    Console.WriteLine($"Error: {e.Message}");

converter.Warning += (s, e) =>
    Console.WriteLine($"Warning: {e.Message}");

// Create document
var document = new HtmlToPdfDocument()
{
    GlobalSettings = new GlobalSettings()
    {
        ColorMode = ColorMode.Color,
        Orientation = Orientation.Portrait,
        PaperSize = PaperKind.A4,
        Margins = new MarginSettings(10, 10, 10, 10)
    },
    Objects = {
        new ObjectSettings()
        {
            Page = "https://www.example.com"
        }
    }
};

// Convert
byte[] pdf = converter.Convert(document);

// Clean up
converter.Dispose();
```

--------------------------------

### BasicConverter Constructor Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/BasicConverter.md

Example of how to create a new instance of the BasicConverter class.

```csharp
var tools = new PdfTools();
var converter = new BasicConverter(tools);
```

--------------------------------

### Timing Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Configures the delay for JavaScript execution and the zoom factor for the page.

```csharp
loadSettings.JSDelay = 2000;      // Wait 2 seconds after JS execution
loadSettings.ZoomFactor = 1.5;    // Zoom to 150%
```

--------------------------------

### Load Method Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/PdfTools.md

Example showing how to load the native wkhtmltopdf library and handle potential exceptions.

```csharp
var tools = new PdfTools();
try
{
    tools.Load();
}
catch (NotSupportedException ex)
{
    Console.WriteLine($"Failed to load wkhtmltopdf: {ex.Message}");
}
```

--------------------------------

### PhaseChanged Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/BasicConverter.md

Example of subscribing to the PhaseChanged event to log conversion progress.

```csharp
converter.PhaseChanged += (sender, args) =>
{
    Console.WriteLine($"[{args.CurrentPhase + 1}/{args.PhaseCount}] {args.Description}");
};
```

--------------------------------

### Warning Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/BasicConverter.md

Example of how to subscribe to the Warning event to handle non-fatal issues.

```csharp
converter.Warning += (sender, args) =>
{
    Console.Out.WriteLine($"WARNING: {args.Message}");
};
```

--------------------------------

### Warning Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/IConverter.md

Example of subscribing to the Warning event to handle conversion warnings.

```csharp
converter.Warning += (sender, args) =>
{
    Console.WriteLine($"Warning: {args.Message}");
};
```

--------------------------------

### Finished Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/IConverter.md

Example of subscribing to the Finished event to determine if the conversion completed successfully.

```csharp
converter.Finished += (sender, args) =>
{
    if (args.Success)
    {
        Console.WriteLine("Conversion completed successfully");
    }
    else
    {
        Console.WriteLine("Conversion failed");
    }
};
```

--------------------------------

### Convert Method Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/BasicConverter.md

Example demonstrating how to use the Convert method to convert an HTML document to PDF.

```csharp
var converter = new BasicConverter(new PdfTools());

var document = new HtmlToPdfDocument()
{
    GlobalSettings = new GlobalSettings()
    {
        ColorMode = ColorMode.Color,
        Orientation = Orientation.Portrait,
        PaperSize = PaperKind.A4
    },
    Objects = {
        new ObjectSettings()
        {
            HtmlContent = "<h1>Invoice</h1><p>Total: $100</p>",
            WebSettings = { DefaultEncoding = "utf-8" }
        }
    }
};

try
{
    byte[] pdf = converter.Convert(document);
    System.IO.File.WriteAllBytes("invoice.pdf", pdf);
}
catch (ArgumentException ex)
{
    Console.WriteLine($"Conversion error: {ex.Message}");
}
```

--------------------------------

### PhaseChanged Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/IConverter.md

Example of subscribing to the PhaseChanged event to monitor the conversion process phases.

```csharp
converter.PhaseChanged += (sender, args) =>
{
    Console.WriteLine($"Phase {args.CurrentPhase}/{args.PhaseCount}: {args.Description}");
};
```

--------------------------------

### Finished Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/BasicConverter.md

Example of how to subscribe to the Finished event to check the success or failure of the conversion.

```csharp
converter.Finished += (sender, args) =>
{
    if (args.Success)
        Console.WriteLine("✓ Conversion successful");
    else
        Console.WriteLine("✗ Conversion failed");
};
```

--------------------------------

### Document Title Setting

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Example of setting the document title metadata.

```csharp
globalSettings.DocumentTitle = "Annual Report 2024";
```

--------------------------------

### PdfTools Constructor Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/PdfTools.md

Example demonstrating how to create a new instance of the PdfTools class.

```csharp
var tools = new PdfTools();
// Library is not loaded yet
```

--------------------------------

### Basic Converter Initialization

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/README.md

Example of creating a BasicConverter instance for single-threaded applications.

```csharp
var converter = new BasicConverter(new PdfTools());
```

--------------------------------

### ProgressChanged Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/IConverter.md

Example of subscribing to the ProgressChanged event to receive progress updates during conversion.

```csharp
converter.ProgressChanged += (sender, args) =>
{
    Console.WriteLine($"Progress: {args.Description}");
};
```

--------------------------------

### Link Handling Configuration

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Examples for configuring how external and local links are handled during PDF generation.

```csharp
settings.UseExternalLinks = true;   // Convert <a href> to PDF links
settings.UseLocalLinks = true;      // Convert internal links
```

--------------------------------

### GlobalSettings Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/HtmlToPdfDocument.md

Example of setting various global PDF document properties like paper size, margins, and title.

```csharp
document.GlobalSettings = new GlobalSettings()
{
    ColorMode = ColorMode.Color,
    Orientation = Orientation.Portrait,
    PaperSize = PaperKind.A4,
    Margins = new MarginSettings(10, 10, 10, 10),
    DocumentTitle = "My Report"
};
```

--------------------------------

### Complete Multi-Page Document Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/HtmlToPdfDocument.md

A comprehensive example showing the creation of a multi-page PDF document with a cover, table of contents, and multiple content pages, followed by conversion.

```csharp
var document = new HtmlToPdfDocument()
{
    GlobalSettings = new GlobalSettings()
    {
        ColorMode = ColorMode.Color,
        Orientation = Orientation.Portrait,
        PaperSize = PaperKind.A4,
        Margins = new MarginSettings(20, 20, 20, 20),
        DocumentTitle = "Invoice #12345"
    }
};

// Add cover page
document.Objects.Add(new CoverSettings()
{
    HtmlContent = @"\
        <html>
        <body style='text-align: center; padding-top: 100px'>
            <h1>Invoice</h1>
            <p>Invoice #12345</p>
            <p>Date: 2024-01-15</p>
        </body>
        </html>"
});

// Add table of contents
document.Objects.Add(new TableOfContentsSettings()
{
    CaptionText = "Contents",
    UseDottedLines = true
});

// Add main content page
document.Objects.Add(new ObjectSettings()
{
    HtmlContent = @"\
        <html>
        <body>
            <h1>Details</h1>
            <p>Invoice details go here...</p>
        </body>
        </html>",
    WebSettings = { DefaultEncoding = "utf-8" },
    HeaderSettings = new HeaderSettings()
    {
        Line = true,
        FontSize = 10,
        Right = "Page [page] of [toPage]"
    },
    FooterSettings = new FooterSettings()
    {
        Line = true,
        Center = "[page]"
    }
});

// Add another page
document.Objects.Add(new ObjectSettings()
{
    Page = "https://example.com/invoice-details"
});

// Convert
var converter = new SynchronizedConverter(new PdfTools());
byte[] pdf = converter.Convert(document);
```

--------------------------------

### Page Numbering Offset

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Example of setting a page offset for numbering.

```csharp
globalSettings.PageOffset = 10;  // Pages numbered starting at 10
```

--------------------------------

### Tools Property Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/BasicConverter.md

Example of accessing the Tools property to get the wkhtmltopdf library version.

```csharp
if (converter.Tools.IsLoaded)
{
    string version = converter.Tools.GetLibraryVersion();
    Console.WriteLine($"wkhtmltopdf version: {version}");
}
```

--------------------------------

### Load Error Handling Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/errors.md

Example demonstrating how to configure LoadSettings to skip objects that fail to load during conversion.

```csharp
// Skip objects that fail to load
objectSettings.LoadSettings = new LoadSettings()
{
    LoadErrorHandling = ContentErrorHandling.Skip
};
```

--------------------------------

### Complete BasicConverter Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/BasicConverter.md

A comprehensive example demonstrating the usage of BasicConverter, including event subscriptions, document creation, and conversion.

```csharp
using System;
using System.IO;
using WkHtmlToPdfDotNet;

class Program
{
    static void Main()
    {
        var converter = new BasicConverter(new PdfTools());
        
        converter.PhaseChanged += (s, e) =>
            Console.WriteLine($"Phase {e.CurrentPhase + 1}/{e.PhaseCount}: {e.Description}");
            
        converter.Error += (s, e) =>
            Console.Error.WriteLine($"Error: {e.Message}");
            
        var document = new HtmlToPdfDocument()
        {
            GlobalSettings = new GlobalSettings()
            {
                ColorMode = ColorMode.Color,
                Orientation = Orientation.Portrait,
                PaperSize = PaperKind.A4,
                Margins = new MarginSettings(20, 20, 20, 20),
                Out = "/tmp/output.pdf"
            },
            Objects = {
                new ObjectSettings()
                {
                    Page = "https://www.example.com"
                }
            }
        };
        
        try
        {
            byte[] pdf = converter.Convert(document);
            Console.WriteLine($"✓ PDF generated: {pdf.Length} bytes");
        }
        finally
        {
            converter.Dispose();
        }
    }
}
```

--------------------------------

### GetLibraryVersion Method Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/PdfTools.md

Example showing how to get the version string of the loaded wkhtmltopdf library.

```csharp
tools.Load();
string version = tools.GetLibraryVersion();
Console.WriteLine($"wkhtmltopdf version: {version}");
```

--------------------------------

### DoConversion Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/PdfTools.md

Demonstrates how to perform a PDF conversion and check for success.

```csharp
bool success = tools.DoConversion(converter);
if (success)
{
    byte[] pdf = tools.GetConversionResult(converter);
}
else
{
    Console.WriteLine("Conversion failed");
}
```

--------------------------------

### Return as Byte Array

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Configure global settings to output the PDF as a byte array.

```csharp
globalSettings.Out = "";  // Empty or omit
byte[] pdf = converter.Convert(document);
```

--------------------------------

### Output Configuration Examples

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Demonstrates how to configure the output of the PDF generation process: returning as bytes, writing to a file, or sending to stdout.

```csharp
// Return PDF as bytes
globalSettings.Out = "";
byte[] pdf = converter.Convert(document);

// Write to file
globalSettings.Out = "/path/to/output.pdf";
converter.Convert(document);

// Send to stdout
globalSettings.Out = "-";
```

--------------------------------

### GetGlobalSetting Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/PdfTools.md

Shows how to retrieve a global setting value, such as the orientation.

```csharp
string orientation = tools.GetGlobalSetting(globalSettings, "orientation");
Console.WriteLine($"Orientation: {orientation}");
```

--------------------------------

### Synchronized Converter Initialization

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/README.md

Example of creating a SynchronizedConverter instance for multi-threaded applications and web servers.

```csharp
var converter = new SynchronizedConverter(new PdfTools());
```

--------------------------------

### Cookie Jar Configuration

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Example of setting a cookie jar file path for wkhtmltopdf.

```csharp
globalSettings.CookieJar = "/path/to/cookies.txt";
```

--------------------------------

### Authentication and Headers

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Configure load settings for authentication (username, password), custom headers, and cookies.

```csharp
loadSettings.Username = "user";
loadSettings.Password = "pass";

loadSettings.CustomHeaders = new Dictionary<string, string>()
{
    { "Authorization", "Bearer token" }
};

loadSettings.Cookies = new Dictionary<string, string>()
{
    { "sessionid", "abc123" }
};
```

--------------------------------

### Write to File

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Configure global settings to write the PDF output directly to a file.

```csharp
globalSettings.Out = "/path/to/file.pdf";
converter.Convert(document);
```

--------------------------------

### JavaScript Execution Configuration

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Examples for enabling or disabling JavaScript execution and browser plugins.

```csharp
webSettings.EnableJavascript = true;  // Allow JS execution
webSettings.enablePlugins = false;    // Disable browser plugins
```

--------------------------------

### Converting Document to File

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/README.md

Example of calling the Convert method when the document is configured for file output.

```csharp
converter.Convert(doc);
```

--------------------------------

### Convert Web Page

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Configure an ObjectSettings to convert a web page by providing its URL.

```csharp
document.Objects.Add(new ObjectSettings()
{
    Page = "https://example.com"
});
```

--------------------------------

### Color and Quality

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Configure global settings for color mode, DPI, and image quality.

```csharp
globalSettings.ColorMode = ColorMode.Color;
globalSettings.DPI = 300;
globalSettings.ImageQuality = 95;
```

--------------------------------

### Usage Example: ContentErrorHandling

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

Example of setting LoadErrorHandling in LoadSettings.

```csharp
loadSettings.LoadErrorHandling = ContentErrorHandling.Skip;
```

--------------------------------

### ObjectSettings Content Source Examples

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Shows how to specify the content source for an object, either by URL/file path or by providing inline HTML.

```csharp
// Load from URL
settings.Page = "https://example.com";

// Load from file
settings.Page = "/path/to/page.html";

// Inline HTML
settings.HtmlContent = "<html><body>Content</body></html>";
```

--------------------------------

### WkHtmlAttribute Usage Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/types.md

Example of using the WkHtmlAttribute to map properties to wkhtmltopdf settings.

```csharp
[WkHtml("orientation")]
public Orientation? Orientation { get; set; }

[WkHtml("size.pageSize")]
public PechkinPaperSize PaperSize { get; set; }
```

--------------------------------

### Error Handling Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/README.md

Example of subscribing to error and warning events to diagnose issues.

```csharp
converter.Error += (s, e) => Console.WriteLine(e.Message);
converter.Warning += (s, e) => Console.WriteLine(e.Message);
```

--------------------------------

### HTML Headers/Footers Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Specifies a URL or file path for custom HTML content to be used as a header or footer.

```csharp
headerSettings.HtmlUrl = "file:///path/to/header.html";
footerSettings.HtmlUrl = "https://example.com/footer.html";
```

--------------------------------

### Font and Encoding Configuration

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Examples for setting the default encoding, minimum font size, and a user-defined stylesheet.

```csharp
webSettings.DefaultEncoding = "utf-8";
webSettings.MinimumFontSize = 10;      // Minimum 10pt font
webSettings.UserStyleSheet = "/path/to/custom.css";  // Apply custom CSS
```

--------------------------------

### SynchronizedConverter Constructor Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/SynchronizedConverter.md

Example of how to instantiate SynchronizedConverter, typically registered in dependency injection.

```csharp
// Typically registered as a singleton in dependency injection
var converter = new SynchronizedConverter(new PdfTools());
```

--------------------------------

### Error Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/IConverter.md

Example of subscribing to the Error event to handle conversion errors.

```csharp
converter.Error += (sender, args) =>
{
    Console.WriteLine($"Error: {args.Message}");
};
```

--------------------------------

### Error Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/BasicConverter.md

Example of how to subscribe to the Error event to log error messages during conversion.

```csharp
converter.Error += (sender, args) =>
{
    Console.Error.WriteLine($"ERROR: {args.Message}");
};
```

--------------------------------

### Security and Error Handling Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Configures security settings like blocking local file access, stopping slow scripts, debugging JavaScript, and handling load errors.

```csharp
loadSettings.BlockLocalFileAccess = true;   // Security: prevent file:// access
loadSettings.StopSlowScript = true;         // Stop long-running scripts
loadSettings.DebugJavascript = true;        // Report JS errors
loadSettings.LoadErrorHandling = ContentErrorHandling.Skip;
```

--------------------------------

### Page Layout Settings

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Example of setting the number of copies, collation, outline generation, and outline depth.

```csharp
globalSettings.Copies = 2;
globalSettings.Collate = true;
globalSettings.Outline = true;
globalSettings.OutlineDepth = 4;
```

--------------------------------

### Solution for Settings Not Applied

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/HtmlToPdfDocument.md

Shows how to correctly initialize GlobalSettings and object-specific settings to ensure they are applied.

```csharp
document.GlobalSettings = new GlobalSettings()
{
    PaperSize = PaperKind.A4
};

// or for object-specific settings
document.Objects.Add(new ObjectSettings()
{
    WebSettings = new WebSettings() { DefaultEncoding = "utf-8" }
});
```

--------------------------------

### Finished Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/errors.md

Example of subscribing to the Finished event to determine if the PDF conversion was successful.

```csharp
converter.Finished += (sender, args) =>
{
    if (args.Success)
    {
        Console.WriteLine("✓ Conversion succeeded");
    }
    else
    {
        Console.WriteLine("✗ Conversion failed");
    }
};

byte[] pdf = converter.Convert(document);
```

--------------------------------

### Headers and Footers

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Configure header and footer settings for object settings, including text and lines.

```csharp
objectSettings.HeaderSettings = new HeaderSettings()
{
    Right = "Page [page] of [toPage]",
    Line = true
};

objectSettings.FooterSettings = new FooterSettings()
{
    Center = "[date]",
    Line = true
};
```

--------------------------------

### Convert Method Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/SynchronizedConverter.md

Example of thread-safe usage of the Convert method within a web controller in ASP.NET.

```csharp
// Thread-safe usage in a web controller
public class PdfController
{
    private readonly IConverter converter;
    
    public PdfController(IConverter converter)
    {
        this.converter = converter;
    }
    
    [HttpPost]
    public IActionResult GeneratePdf([FromBody] PdfRequest request)
    {
        var document = new HtmlToPdfDocument()
        {
            GlobalSettings = new GlobalSettings()
            {
                ColorMode = ColorMode.Color,
                PaperSize = PaperKind.A4
            },
            Objects = {
                new ObjectSettings()
                {
                    HtmlContent = request.HtmlContent
                }
            }
        };
        
        byte[] pdf = converter.Convert(document);
        
        return File(pdf, "application/pdf", "document.pdf");
    }
}
```

--------------------------------

### Content Placement Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Sets the left, center, and right text for headers or footers, including placeholders for page numbers, date, and time.

```csharp
headerSettings.Left = "Company Name";
headerSettings.Center = "[date]";
headerSettings.Right = "Page [page] of [toPage]";
```

--------------------------------

### Dispose Method Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/BasicConverter.md

Example showing how to properly dispose of the BasicConverter instance using a 'using' statement.

```csharp
using (var converter = new BasicConverter(new PdfTools()))
{
    byte[] pdf = converter.Convert(document);
}
// Converter is disposed automatically
```

--------------------------------

### Invoke Method Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/SynchronizedConverter.md

Example demonstrating a custom operation executed on the background thread using the Invoke method.

```csharp
// Custom operation on the background thread
var result = converter.Invoke(() =>
{
    Console.WriteLine("Running on background thread");
    return "Success";
});
```

--------------------------------

### Content Rendering Configuration

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/configuration.md

Examples for controlling content rendering, including backgrounds, image loading, print media type, and intelligent shrinking.

```csharp
webSettings.Background = true;              // Render CSS backgrounds
webSettings.LoadImages = true;              // Load external images
webSettings.PrintMediaType = true;          // Use print CSS media
webSettings.EnableIntelligentShrinking = true;  // Fit content to page
```

--------------------------------

### Warning Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/errors.md

Example of subscribing to the Warning event to count and log warning messages during PDF conversion.

```csharp
int warningCount = 0;

converter.Warning += (sender, args) =>
{
    warningCount++;
    Console.WriteLine($"[WARNING] {args.Message}");
};

byte[] pdf = converter.Convert(document);

if (warningCount > 0)
{
    Console.WriteLine($"Conversion completed with {warningCount} warnings");
}
```

--------------------------------

### Error Event Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/errors.md

Example of how to subscribe to the Error event to capture and log error messages during PDF conversion.

```csharp
var errorMessages = new List<string>();

converter.Error += (sender, args) =>
{
    errorMessages.Add(args.Message);
    Console.Error.WriteLine($"[ERROR] {args.Message}");
};

byte[] pdf = converter.Convert(document);

if (errorMessages.Any())
{
    Console.WriteLine($"Conversion had {errorMessages.Count} errors");
}
```

--------------------------------

### JavaScript and Styling

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/QUICK_REFERENCE.md

Configure web settings for JavaScript, image loading, and default encoding, as well as load settings for JavaScript delay.

```csharp
objectSettings.WebSettings = new WebSettings()
{
    EnableJavascript = true,
    LoadImages = true,
    DefaultEncoding = "utf-8"
};

objectSettings.LoadSettings = new LoadSettings()
{
    JSDelay = 2000
};
```

--------------------------------

### ProcessingDocument Property Example

Source: https://github.com/hakanl/wkhtmltopdf-dotnet/blob/master/_autodocs/api-reference/BasicConverter.md

Example of using the ProcessingDocument property within an event handler to access the current document being converted.

```csharp
converter.PhaseChanged += (sender, args) =>
{
    var doc = converter.ProcessingDocument;
    Console.WriteLine($"Processing document with {doc.GetObjects().Count()} objects");
};
```