Which namespace and assembly contain Installation?

Installation is in the IronPdf namespace, shipped in IronPdf.dll. It is declared public static class, so every member is accessed through the type name with no instantiation. It is the type a developer configures at application startup to set deployment paths, performance limits, and engine behavior.

What is the difference between Installation and License in IronPDF?

Installation holds runtime deployment and performance configuration: paths (TempFolderPath, ChromeBrowserCachePath), concurrency (ChromeBrowserLimit, SingleProcess), GPU mode, and engine lifecycle (Initialize, SkipInitialization, SkipShutdown). License holds the IronPDF product key. Installation has no LicenseKey property; the license is set on the separate IronPdf.License class via License.LicenseKey before the first render.

How do you configure IronPDF in ASP.NET Core?

Set Installation properties in Program.cs (or Startup.ConfigureServices for earlier ASP.NET Core versions) before the application starts serving requests. Assign TempFolderPath, ChromeBrowserLimit, and any behavior flags from appsettings.json or environment variables. Set License.LicenseKey, then call Installation.Initialize() to preload the rendering engine so the first request does not pay the warm-up cost.

When should you call Installation.Initialize()?

Call Initialize() once during application startup, after setting deployment properties and the license. The method preloads the Chromium engine so the first render avoids the warm-up cost. For web applications, place the call at the end of startup configuration; for desktop or batch applications, before the first PDF operation. Skip the call when SkipInitialization is true.

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

Use Installation when you need to configure IronPDF's runtime at application startup, before any ChromePdfRenderer or PdfDocument operation. It exposes static properties that control deployment paths, performance tuning, and engine behavior, plus three static methods (Initialize, CleanupTempImages, ConnectToIronPdfHost) that operate on the running process. Configuration is process-global.

The class belongs at the very top of an IronPDF wiring sequence because the renderer and the underlying native engine read these properties at construction time. A production web service preloads Chromium with Installation.Initialize() so the first request does not pay the warm-up cost, points TempFolderPath at fast storage, and caps ChromeBrowserLimit to keep memory predictable. A Docker or Linux deployment sets LinuxAndDockerDependenciesAutoConfig so the engine handles its own native packages. A privacy-sensitive deployment opts out of SendAnonymousAnalyticsAndCrashData.

Configuration falls into four functional groups. Path properties (TempFolderPath, ChromeBrowserCachePath, CustomDeploymentDirectory) tell IronPDF where to write intermediate files, cache the embedded Chromium data, and locate native binaries. Performance properties (ChromeBrowserLimit, JobQueueWatchdogTimeout, ChromeGpuMode, SingleProcess) tune concurrency, render timeouts, GPU acceleration, and process model. Behavior flags (EnableWebSecurity, AutomaticallyDownloadNativeBinaries, LinuxAndDockerDependenciesAutoConfig, SkipInitialization, SkipShutdown, DebugJobQueue) toggle high-level features. Read-only state (IronPdfEngineVersion, ConnectionType) reports on the active engine. Two utility methods complete the surface: CleanupTempImages removes accumulated intermediate files older than an optional TimeSpan, and ConnectToIronPdfHost attaches the process to an external IronPDF engine via an IronPdfConnectionConfiguration. Reach for the installation overview guide when deciding which of these setup choices a deployment needs.

using IronPdf;

// Configure at application startup, before any ChromePdfRenderer or PdfDocument call
Installation.TempFolderPath                    = @"D:\fast-ssd\ironpdf-temp";
Installation.ChromeBrowserLimit                = 4;
Installation.LinuxAndDockerDependenciesAutoConfig = true;
Installation.SendAnonymousAnalyticsAndCrashData    = false;

// Apply the IronPDF license on the separate License class
License.LicenseKey = "YOUR-LICENSE-KEY";

// Pre-load the rendering engine so the first request does not pay the warm-up cost
Installation.Initialize();

// First render is fast because Chromium is already initialized
var renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Hello</h1>");
pdf.SaveAs("output.pdf");

// Optional periodic cleanup of accumulated intermediate files
Installation.CleanupTempImages(TimeSpan.FromHours(24));

For platform-specific setup, the Linux deployment guide and the Docker deployment guide cover the dependencies and path layout. The license keys guide covers applying a license at startup, which is handled on the separate License class rather than on Installation.

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

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:").
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

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()

Class Installation

Inheritance

Namespace: IronPdf

Assembly: IronPdf.dll

Syntax

Fields

SendAnonymousAnalyticsAndCrashData

Declaration

Field Value

Properties

AutomaticallyDownloadNativeBinaries

Declaration

Property Value

Remarks

ChromeBrowserCachePath

Declaration

Property Value

ChromeBrowserLimit

Declaration

Property Value

ChromeGpuMode

Declaration

Property Value

ConnectionType

Declaration

Property Value

CustomDeploymentDirectory

Declaration

Property Value

DebugJobQueue

Declaration

Property Value

EnableWebSecurity

Declaration

Property Value

IronPdfEngineVersion

Declaration

Property Value

JobQueueWatchdogTimeout

Declaration

Property Value

Exceptions

LinuxAndDockerDependenciesAutoConfig

Declaration

Property Value

See Also

SingleProcess

Declaration

Property Value

Remarks

SkipInitialization

Declaration

Property Value

Remarks

SkipShutdown

Declaration

Property Value

Remarks

TempFolderPath

Declaration

Property Value

Exceptions

Methods

CleanupTempImages(Nullable<TimeSpan>)

Declaration

Parameters

ConnectToIronPdfHost(IronPdfConnectionConfiguration)

Declaration

Parameters

See Also

Initialize()

Declaration