Class Installation

One-time global configuration for IronPDF deployment, licensing, and performance tuning. Configure once at application startup before creating any PDF operations for optimal results.

// Application startup configuration:
Installation.LicenseKey = "YOUR-LICENSE-KEY";
Installation.Initialize();  // Warm up rendering engines

// Docker/Linux configuration:
Installation.LinuxAndDockerDependenciesAutoConfig = true;
Installation.ChromeGpuMode = ChromeGpuModes.Disabled;

// High-performance server configuration:
Installation.ChromeBrowserLimit = 20;  // More concurrent browsers
Installation.TempFolderPath = @"/fast-ssd/temp";  // Fast storage

Call Initialize() at startup to avoid first-render delays

Configure before any PDF operations for settings to take effect

See: https://ironpdf.com/how-to/installation/

Inheritance
System.Object
Installation
Namespace: IronPdf
Assembly: IronPdf.dll
Syntax
public static class Installation : Object

Working with PDF generation in IronPDF runs through Installation. It represents one-time global configuration for IronPDF deployment, licensing, and performance tuning.

Installation matters when an application needs to configure or invoke PDF generation from C# code. The class encapsulates the related options and behavior in a single object that is set up once and reused across render or processing calls. Typical scenarios include batch generation pipelines, templated document workflows, and integration with existing C# document services.

To use Installation, instantiate or obtain it from the relevant entry point in the IronPDF C# API. Key properties include AutomaticallyDownloadNativeBinaries, ChromeBrowserCachePath, ChromeBrowserLimit, ChromeGpuMode. Assign options or invoke methods on the instance to configure or perform the operation. The installation covers typical usage in C# end to end.

using IronPdf;

// Obtain Installation from the relevant entry point in the IronPDF API
void Configure(Installation instance)
{
    var current = instance.AutomaticallyDownloadNativeBinaries;
    instance.CleanupTempImages();
}

For the broader workflow, see the installation guide in the IronPDF C# documentation. For broader context, the PDF generation portion of the IronPDF C# API contains related types that work with Installation directly. Installation exposes additional members beyond those highlighted above; the reference tables on this page list the full set. In application code, treat Installation as a configured object that is constructed once and reused across operations rather than instantiated per call. Configuration is generally idempotent: assigning the same property value twice has the same effect as assigning it once. For diagnostic purposes, inspect the relevant Installation property after each operation to confirm the configured state. See the constructors, properties, and methods tables below for the complete API surface of Installation. Application code typically obtains or instantiates a single Installation and shares it across multiple IronPDF operations rather than recreating it per call.

Fields

SendAnonymousAnalyticsAndCrashData

Opt in or out of sending anonymous usage statistics about IronPDF usage and performance to help us improve the product and developer experience.

Usage statistics are never sent in commercially deployed projects (when a license key is applied), only during development usage.

Declaration
public static bool SendAnonymousAnalyticsAndCrashData
Field Value
Type Description
System.Boolean

Properties

AutomaticallyDownloadNativeBinaries

Set to True to let IronPDF try to download missing NativeBinaries from the internet at a runtime.

Declaration
public static bool AutomaticallyDownloadNativeBinaries { get; set; }
Property Value
Type Description
System.Boolean
Remarks

Useful for IronPdf.Slim

ChromeBrowserCachePath

Disk cache path for chrome browser instances

Declaration
public static string ChromeBrowserCachePath { get; set; }
Property Value
Type Description
System.String

ChromeBrowserLimit

Maximum number of concurrent browsers when using the Chrome renderer By default, this is set to System.Environment.ProcessorCount.

Declaration
public static int ChromeBrowserLimit { get; set; }
Property Value
Type Description
System.Int32

ChromeGpuMode

Chrome renderer GPU compatibility mode. In special environment like Docker or Cloud Service please use ChromeGpuModes.Disabled

Declaration
public static ChromeGpuModes ChromeGpuMode { get; set; }
Property Value
Type Description
ChromeGpuModes

ConnectionType

Get the current connection type.

Declaration
public static Nullable<IronPdfConnectionType> ConnectionType { get; }
Property Value
Type Description
System.Nullable<IronPdfConnectionType>

CustomDeploymentDirectory

Custom deployment directory for renderer native binaries.

Declaration
public static string CustomDeploymentDirectory { get; set; }
Property Value
Type Description
System.String

DebugJobQueue

Enable or disable the logging of the job queue. Can use IronSoftware.JobQueue.JobQueueLogger.ExportToCsv(System.String) to export the job queue log to a CSV file.

Declaration
public static bool DebugJobQueue { get; set; }
Property Value
Type Description
System.Boolean

EnableWebSecurity

Enable web security for Chrome renderer. Disabled by default.

Enabling web security will disable operations which require local disk access or cross-origin requests.

Useful when injecting untrusted HTML from users.

Declaration
public static bool EnableWebSecurity { get; set; }
Property Value
Type Description
System.Boolean

IronPdfEngineVersion

Declaration
public static string IronPdfEngineVersion { get; }
Property Value
Type Description
System.String

JobQueueWatchdogTimeout

Default watchdog timeout for queued Chrome jobs. If a render does not complete within this window, the queue slot is reclaimed and the awaiting caller observes a TimeoutException. This prevents a single hung native call from leaking a slot until the engine deadlocks under load. Defaults to 5 minutes.

Declaration
public static TimeSpan JobQueueWatchdogTimeout { get; set; }
Property Value
Type Description
System.TimeSpan
Exceptions
Type Condition
System.ArgumentOutOfRangeException

Setter throws when value is System.TimeSpan.Zero or any other non-positive value, except for System.Threading.Timeout.InfiniteTimeSpan which is the documented "no watchdog" sentinel. Accepting System.TimeSpan.Zero here would silently re-enable the deadlock this whole fix is closing. Validation is enforced once at the underlying field (IronSoftware.JobQueue.JobQueueManager.DefaultWatchdogTimeout) so all surfaces. This property, GlobalChromeSettings.JobQueueWatchdogTimeout, and the job_queue_watchdog_timeout_seconds engine CLI flag, inherit the same clamp.

LinuxAndDockerDependenciesAutoConfig

Auto-installs Linux/Docker dependencies (libgdiplus, fonts, Chrome libs) on first run. Essential for containerized deployments - saves hours of manual configuration.

// Docker container startup:
Installation.LinuxAndDockerDependenciesAutoConfig = true;
Installation.ChromeGpuMode = ChromeGpuModes.Disabled;
Installation.Initialize();  // Installs dependencies

// Manual setup (for production images):
Installation.LinuxAndDockerDependenciesAutoConfig = false;
// Dependencies pre-installed in Dockerfile

// Azure App Service:
Installation.LinuxAndDockerDependenciesAutoConfig = true;
// Automatically configures Linux environment

First run takes 2-3 minutes to install packages

Requires apt-get access - may fail in restricted containers

See: https://ironpdf.com/docs/questions/docker-linux/

Declaration
public static bool LinuxAndDockerDependenciesAutoConfig { get; set; }
Property Value
Type Description
System.Boolean
See Also
IronSoftware.Deployment.DeploymentEngine.SkipInstallCommands

SingleProcess

Forces Chrome renderer to perform everything in the current process, rather than using subprocesses

Declaration
public static bool SingleProcess { get; set; }
Property Value
Type Description
System.Boolean
Remarks

Warning! This feature is experimental and unstable. Useful for environments where execution permissions are not possible.

SkipInitialization

Set to True to skip certain initialization routines, e.g. Cef initialization

Declaration
public static bool SkipInitialization { get; set; }
Property Value
Type Description
System.Boolean
Remarks

Useful for certain environments which have persistence, e.g. IIS or web apps

SkipShutdown

Set to True to skip certain shutdown routines, e.g. Cef shutdown

Declaration
public static bool SkipShutdown { get; set; }
Property Value
Type Description
System.Boolean
Remarks

Useful for certain environments which have persistence, e.g. IIS or web apps

TempFolderPath

The temporary folder path which temporary files and rendering engine DLLs will be deployed to where necessary. The default location is the system temp folder which is appropriate for most use cases.

Declaration
public static string TempFolderPath { get; set; }
Property Value
Type Description
System.String
Exceptions
Type Condition
System.ArgumentException

value is a zero-length string, contains only white space, or contains one or more of the invalid characters defined in System.IO.Path.GetInvalidPathChars. -or- The system could not retrieve the absolute path.
System.Security.SecurityException

The caller does not have the required permissions.
System.ArgumentNullException

value is null.
System.NotSupportedException

value contains a colon (":") that is not part of a volume identifier (for example, "c:&quot;).
System.IO.PathTooLongException

The specified path, file name, or both exceed the system-defined maximum length.
IronPdfProductException

The property TempFolderPath is already initialized.

Methods

CleanupTempImages(Nullable<TimeSpan>)

Method to remove temporary images from TempFolderPath

If you used a customTempFolderPath then set TempFolderPath to point towards your deployment directory before you call this cleanup method.

Declaration
public static void CleanupTempImages(Nullable<TimeSpan> expirationTime = null)
Parameters
Type Name Description
System.Nullable<System.TimeSpan> expirationTime

Time from last access for files to delete. All files are deleted by default.

ConnectToIronPdfHost(IronPdfConnectionConfiguration)

Connect to an IronPdf server using the specified connection parameters

Declaration
public static void ConnectToIronPdfHost(IronPdfConnectionConfiguration configuration)
Parameters
Type Name Description
IronPdfConnectionConfiguration configuration

IronPdf server connection parameters
See Also
IronPdf.GrpcLayer.IronPdfConnectionConfiguration.Cloud

Initialize()

Pre-loads Chrome engine and dependencies to eliminate first-render delays (saves 1-3 seconds). Essential for production servers and web applications where response time matters.

// In Program.cs or Global.asax.cs:
Installation.Initialize();  // One-time at startup

// Later renders are instant:
var renderer = new ChromePdfRenderer();  // No delay
var pdf = renderer.RenderHtmlAsPdf(html);  // Fast!

// Web application startup:
public void ConfigureServices(IServiceCollection services) {
    Installation.LicenseKey = Config["IronPdf:LicenseKey"];
    Installation.Initialize();  // Warm up once
}

Saves 1-3 seconds on first PDF generation

May increase application startup time by 1-2 seconds

See: https://ironpdf.com/how-to/installation/#initialize

Declaration
public static void Initialize()