How to use Cookies with IronPDF in C#

What Is the RequestContext Property?

Set the RequestContext property to RequestContexts.Global before applying cookies. Create the ChromeHttpLoginCredentials class and pass it to the ApplyCookies method. The renderer then renders HTML content to PDF with cookies.

The RequestContext property works with HTTP request headers and authentication. It determines cookie sharing between rendering sessions, critical for applications maintaining session state across multiple PDF generations.

How Do I Use the ApplyCookies Method?

Apply cookies using IronPDF:

:path=/static-assets/pdf/content-code-examples/how-to/cookies-apply-cookies.cs

using IronPdf;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global;

ChromeHttpLoginCredentials credentials = new ChromeHttpLoginCredentials() {
    NetworkUsername = "testUser",
    NetworkPassword = "testPassword"
};

string uri = "http://localhost:51169/Invoice";

// Apply cookies
renderer.ApplyCookies(uri, credentials);

This approach works when converting ASPX pages to PDF requiring authentication or with ASP.NET MVC applications.

Which RequestContext Should I Choose?

RequestContexts Enum defines browser request contexts establishing relationships between renders. It manages cookies and user preferences.

• Isolated: Creates new, isolated request contexts. Prevents current renders from being affected by previous renders. Ideal for multi-threaded PDF generation.
• Global: Uses shared global request context between all renders. Persists browser states between renders. Perfect for maintaining session data across PDF operations.
• Auto: Defaults to IronPdf.Rendering.RequestContexts.Isolated. Switches to IronPdf.Rendering.RequestContexts.Global if IronPdf.ChromePdfRenderer.ApplyCookies(System.String, IronPdf.ChromeHttpLoginCredentials) was invoked.

When implementing cookies in Blazor Server applications, choose the appropriate RequestContext to maintain proper session state between server-side renders.

What Are Custom Cookies in IronPDF?

Custom cookies require setting the CustomCookies property. This property accepts string key-value pair dictionaries. Custom cookies handle complex authentication systems or pass application-level data during rendering.

Custom cookies differ from standard HTTP cookies by allowing any key-value pair definition. This flexibility suits modern web applications using JWT tokens, session IDs, or custom authentication mechanisms.

How Do I Implement Custom Cookies?

Apply custom cookies using IronPDF:

:path=/static-assets/pdf/content-code-examples/how-to/cookies-apply-custom-cookies.cs

using IronPdf;
using System;
using System.Collections.Generic;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

Dictionary<string, string> customCookies = new Dictionary<string, string>();

// Apply custom cookies
renderer.RenderingOptions.CustomCookies = customCookies;

var uri = new Uri("https://localhost:44362/invoice");
PdfDocument pdf = renderer.RenderUrlAsPdf(uri);

This approach suits JavaScript-heavy sites relying on cookies for state management or implementing custom logging solutions.

When Should I Use Custom Cookies vs Standard Cookies?

Custom cookies handle specific session data or authentication tokens not managed by standard HTTP credentials. Use them with custom authentication systems or to maintain user preferences during PDF generation.

Standard cookies (via ApplyCookies method) suit:

• Basic HTTP authentication
• Windows authentication environments
• Simple session management

Custom cookies excel for:

• JWT token-based authentication
• Complex session management with multiple parameters
• Third-party authentication providers (OAuth, SAML)
• User preferences and settings maintenance
• Analytics and tracking requirements

What Are Common Issues with Cookie Implementation?

Common issues include cookies not persisting between renders using Isolated context, authentication failures from incorrect cookie values, and timing issues where cookies expire before PDF generation. Verify cookie validity and consider Global context for persistent sessions.

Troubleshooting tips:

1. Cookie Expiration: Verify cookies haven't expired. Implement refresh logic for short-lived tokens.
2. Domain Restrictions: Ensure cookie domains match the rendered URL.
3. Secure Cookies: Configure secure cookies properly when rendering HTTPS URLs.
4. SameSite Policies: Consider browser SameSite cookie policies affecting cross-origin requests.

For advanced authentication and cookie scenarios, see the rendering options documentation covering all available PDF generation customization settings.