如何在 C# 中使用 IronPDF 處理 Cookies

何謂 RequestContext 屬性？

在套用 Cookie 之前，請將 RequestContext 屬性設定為 RequestContexts.Global。 建立 ChromeHttpLoginCredentials 類別，並將其傳遞給 ApplyCookies 方法。 渲染器隨後會將 HTML 內容連同 Cookie 一起渲染為 PDF。

RequestContext 屬性適用於 HTTP 請求標頭與驗證機制。 此設定決定渲染會話之間的 Cookie 共享機制，對於需在多次 PDF 生成過程中維持會話狀態的應用程式至關重要。

如何使用 ApplyCookies 方法？

使用 IronPDF 套用 Cookie：

: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);

Imports IronPdf

' Instantiate ChromePdfRenderer
Private renderer As New ChromePdfRenderer()

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

Dim credentials As New ChromeHttpLoginCredentials() With {
	.NetworkUsername = "testUser",
	.NetworkPassword = "testPassword"
}

Dim uri As String = "http://localhost:51169/Invoice"

' Apply cookies
renderer.ApplyCookies(uri, credentials)

此方法適用於將需要驗證的 ASPX 頁面轉換為 PDF，或處理 ASP.NET MVC 應用程式時。

我該選擇哪個 RequestContext ？

RequestContexts Enum 定義瀏覽器請求上下文，用以建立渲染器之間的關聯。 它負責管理 Cookie 和使用者偏好設定。

• Isolated：建立新的、隔離的請求上下文。 防止當前渲染結果受到先前渲染結果的影響。 非常適合用於多執行緒 PDF 生成。
• Global：在所有渲染之間共用全域請求上下文。 在每次渲染之間保留瀏覽器狀態。 非常適合在 PDF 操作過程中維持會話資料。
• Auto：預設值為 IronPdf.Rendering.RequestContexts.Isolated。 若已呼叫 IronPdf.ChromePdfRenderer.ApplyCookies(System.String, IronPdf.ChromeHttpLoginCredentials)，則切換至 IronPdf.Rendering.RequestContexts.Global。

在 Blazor Server 應用程式中實作 Cookie 時，請選擇適當的 RequestContext 以維持伺服器端渲染之間的正確會話狀態。

IronPDF 中的自訂 Cookie 是什麼？

CustomCookies 需設定 CustomCookies 屬性。 此屬性接受字串鍵值對字典。 自訂 Cookie 可用於處理複雜的驗證系統，或在渲染過程中傳遞應用程式層級的資料。

自訂 Cookie 與標準 HTTP Cookie 的區別在於，它允許定義任何鍵值對。 這種靈活性適用於使用 JWT 憑證、會話 ID 或自訂驗證機制的現代網路應用程式。

如何實作自訂 Cookie？

使用 IronPDF 套用自訂 Cookie：

: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);

Imports IronPdf
Imports System
Imports System.Collections.Generic

' Instantiate ChromePdfRenderer
Private renderer As New ChromePdfRenderer()

Private customCookies As New Dictionary(Of String, String)()

' Apply custom cookies
renderer.RenderingOptions.CustomCookies = customCookies

Dim uri As New Uri("https://localhost:44362/invoice")
Dim pdf As PdfDocument = renderer.RenderUrlAsPdf(uri)

此方法適用於大量使用 JavaScript 且依賴 Cookie 進行狀態管理，或實作自訂記錄解決方案的網站。

何時該使用自訂 Cookie 而非標準 Cookie？

自訂 Cookie 用於處理特定會話資料或驗證憑證，這些資料並非由標準 HTTP 憑證所管理。 可將其與自訂驗證系統搭配使用，或在生成 PDF 時用於維持使用者偏好設定。

標準的 Cookie（透過 ApplyCookies 方法）適用於：

• 基本 HTTP 驗證
• Windows 驗證環境
• 簡易的會話管理

自訂 Cookie 特別適用於：

• 基於 JWT 憑證的驗證
• 具備多參數的複雜會話管理
• 第三方驗證服務提供者（OAuth、SAML）
• 使用者偏好設定與設定維護
• 分析與追蹤需求

Cookie 實作常見有哪些問題？

常見問題包括：使用 Isolated 上下文時，Cookie 無法在渲染之間保留；因 Cookie 值錯誤導致的驗證失敗；以及 Cookie 在 PDF 生成前過期所引發的時序問題。 驗證 Cookie 的有效性，並針對持久化會話考量 Global 的上下文。

疑難排解提示：

1. Cookie 過期：確認 Cookie 尚未過期。 為短效期憑證實作刷新邏輯。
2. 網域限制：確保 Cookie 網域與渲染後的 URL 相符。
3. 安全 Cookie：在渲染 HTTPS URL 時，請正確設定安全 Cookie。
4. SameSite 政策：請考量影響跨來源請求的瀏覽器 SameSite Cookie 政策。

關於進階驗證與 Cookie 情境，請參閱渲染選項文件，該文件涵蓋所有可用的 PDF 生成自訂設定。