Como eu renderizo uma página protegida por login como um PDF com IronPDF?

Defina RequestContext como Global e preencha CustomCookies com o cookie de sessão do usuário antes de chamar RenderUrlAsPdf . O mecanismo do Chrome do IronPDF se autenticará com esses cookies e renderizará a página protegida.

Qual é a diferença entre ApplyCookies e CustomCookies no IronPDF?

ApplyCookies faz login usando credenciais HTTP (autenticação básica ou Windows) e captura os cookies de sessão resultantes no contexto global. CustomCookies permite que você forneça pares de chave-valor de cookies diretamente — útil para tokens JWT, cookies OAuth e sessões com múltiplos parâmetros.

O que é RequestContext e quando devo usar Global vs Isolated?

Use Global quando várias renderizações compartilham a mesma sessão autenticada (por exemplo, geração em lote de faturas para um usuário). Use Isolated ao renderizar para muitos usuários diferentes simultaneamente, para que cada renderização tenha um estado de cookie limpo e as sessões não possam vazar entre os usuários.

O IronPDF pode lidar com autenticação JWT e OAuth para renderização de PDF?

Sim. Passe os valores dos tokens em CustomCookies como pares de chave-valor (por exemplo, auth_token e refresh_token ). O IronPDF os encaminha com cada solicitação que o mecanismo Chrome faz para essa renderização.

Por que meu PDF é renderizado como uma página em branco ou tela de login?

As causas mais comuns são cookies de sessão expirados, domínios de cookies incompatíveis, restrições de cookies seguros em URLs HTTPS e bloqueios de política SameSite em solicitações de origem cruzada. Verifique se os cookies são válidos e correspondem ao domínio de destino antes de renderizar.

A biblioteca C# PDF

Explore IronPDF Comece seu teste gratuito

HTML para PDF

Online Demo Veja todos os exemplos de código %s

using IronPdf;

// Disable local disk access or cross-origin requests
Installation.EnableWebSecurity = true;

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

// Create a PDF from a HTML string using C#
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export to a file or Stream
pdf.SaveAs("output.pdf");

// Advanced Example with HTML Assets
// Load external html assets: Images, CSS and JavaScript.
// An optional BasePath 'C:\site\assets\' is set as the file location to load assets from
var myAdvancedPdf = renderer.RenderHtmlAsPdf("<img src='icons/iron.png'>", @"C:\site\assets\");
myAdvancedPdf.SaveAs("html-with-assets.pdf");

using IronPdf;

// Disable local disk access or cross-origin requests
Installation.EnableWebSecurity = true;

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

// Create a PDF from a HTML string using C#
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export to a file or Stream
pdf.SaveAs("output.pdf");

// Advanced Example with HTML Assets
// Load external html assets: Images, CSS and JavaScript.
// An optional BasePath 'C:\site\assets\' is set as the file location to load assets from
var myAdvancedPdf = renderer.RenderHtmlAsPdf("<img src='icons/iron.png'>", @"C:\site\assets\");
myAdvancedPdf.SaveAs("html-with-assets.pdf");

PM >

Install-Package IronPdf

COMPARAÇÃO DE PRODUTOS

Explore as melhores alternativas ao PDFsharp para converter PDFs em imagens.

Curtis Chau

Updated: 5 de julho de 2026

A maioria dos trabalhos HTML-to-PDF falha pelo mesmo motivo: a página só fica correta depois que um usuário se autentica. A IronPDF usa um mecanismo do Chrome, então vê o que um navegador não autenticado veria, uma tela de login ou um casco vazio, até que você forneça os cookies corretos. Três componentes da API resolvem isso, a propriedade RequestContext, o método ApplyCookies e o dicionário CustomCookies. Aqui é onde cada um se encaixa, com um trecho correspondente.

A fatura de um cliente está em uma rota protegida por sessão, e seu aplicativo já possui a sessão deles. Passe esse ID de sessão diretamente através CustomCookies:

using IronPdf;
using System.Collections.Generic;

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global;
renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
{
    { "ASP.NET_SessionId", sessionId }
};

renderer.RenderUrlAsPdf("https://app.example.com/account/invoices/1042")
        .SaveAs("invoice-1042.pdf");

using IronPdf;
using System.Collections.Generic;

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global;
renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
{
    { "ASP.NET_SessionId", sessionId }
};

renderer.RenderUrlAsPdf("https://app.example.com/account/invoices/1042")
        .SaveAs("invoice-1042.pdf");

Imports IronPdf
Imports System.Collections.Generic

Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global
renderer.RenderingOptions.CustomCookies = New Dictionary(Of String, String) From {
    {"ASP.NET_SessionId", sessionId}
}

renderer.RenderUrlAsPdf("https://app.example.com/account/invoices/1042").SaveAs("invoice-1042.pdf")

Imports IronPdf
Imports System.Collections.Generic

Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global
renderer.RenderingOptions.CustomCookies = New Dictionary(Of String, String) From {
    {"ASP.NET_SessionId", sessionId}
}

renderer.RenderUrlAsPdf("https://app.example.com/account/invoices/1042").SaveAs("invoice-1042.pdf")

Para autenticação básica ou do Windows, use ApplyCookies em vez disso. Assina no URL com as credenciais fornecidas e captura os cookies resultantes no contexto global, que a renderização seguinte reutiliza:

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global;

var credentials = new ChromeHttpLoginCredentials
{
    NetworkUsername = "svc_reports",
    NetworkPassword = "your_password"
};

string uri = "https://app.example.com/account/invoices/1042";
renderer.ApplyCookies(uri, credentials);

renderer.RenderUrlAsPdf(uri).SaveAs("invoice-1042.pdf");

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global;

var credentials = new ChromeHttpLoginCredentials
{
    NetworkUsername = "svc_reports",
    NetworkPassword = "your_password"
};

string uri = "https://app.example.com/account/invoices/1042";
renderer.ApplyCookies(uri, credentials);

renderer.RenderUrlAsPdf(uri).SaveAs("invoice-1042.pdf");

Imports IronPdf

Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global

Dim credentials As New ChromeHttpLoginCredentials With {
    .NetworkUsername = "svc_reports",
    .NetworkPassword = "your_password"
}

Dim uri As String = "https://app.example.com/account/invoices/1042"
renderer.ApplyCookies(uri, credentials)

renderer.RenderUrlAsPdf(uri).SaveAs("invoice-1042.pdf")

Imports IronPdf

Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global

Dim credentials As New ChromeHttpLoginCredentials With {
    .NetworkUsername = "svc_reports",
    .NetworkPassword = "your_password"
}

Dim uri As String = "https://app.example.com/account/invoices/1042"
renderer.ApplyCookies(uri, credentials)

renderer.RenderUrlAsPdf(uri).SaveAs("invoice-1042.pdf")

Autenticação baseada em token e de terceiros

Aplicativos modernos raramente dependem de credenciais HTTP simples. Eles se autenticam com JWTs, OAuth ou SAML, frequentemente armazenando o resultado em um cookie. Como CustomCookies aceita qualquer par chave-valor, um token de portador ou cookie de provedor de identidade pode ser inserido diretamente:

renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
{
    { "auth_token", jwt },
    { "refresh_token", refreshToken }
};

renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
{
    { "auth_token", jwt },
    { "refresh_token", refreshToken }
};

Imports System.Collections.Generic

renderer.RenderingOptions.CustomCookies = New Dictionary(Of String, String) From {
    {"auth_token", jwt},
    {"refresh_token", refreshToken}
}

Imports System.Collections.Generic

renderer.RenderingOptions.CustomCookies = New Dictionary(Of String, String) From {
    {"auth_token", jwt},
    {"refresh_token", refreshToken}
}

Documentos personalizados e localizados

Cookies frequentemente carregam estado de localidade, moeda ou sinalizadores de recursos. Encaminhe-os, e o PDF corresponderá ao que aquele usuário específico vê, no idioma e moeda corretos:

renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
{
    { "locale", "en-AU" },
    { "currency", "AUD" },
    { "feature_newLayout", "on" }
};

renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
{
    { "locale", "en-AU" },
    { "currency", "AUD" },
    { "feature_newLayout", "on" }
};

renderer.RenderingOptions.CustomCookies = New Dictionary(Of String, String) From {
    {"locale", "en-AU"},
    {"currency", "AUD"},
    {"feature_newLayout", "on"}
}

renderer.RenderingOptions.CustomCookies = New Dictionary(Of String, String) From {
    {"locale", "en-AU"},
    {"currency", "AUD"},
    {"feature_newLayout", "on"}
}

Geração em lote que compartilha uma sessão

Para gerar muitos PDFs para o mesmo usuário autenticado em sequência, defina RequestContext para Global. O estado do navegador, incluindo cookies, persiste entre renderizações, então você autentica uma vez em vez de por documento:

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global;
renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
{
    { "ASP.NET_SessionId", sessionId }
};

foreach (var id in invoiceIds)
{
    renderer.RenderUrlAsPdf($"https://app.example.com/invoices/{id}")
            .SaveAs($"invoice-{id}.pdf");
}

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Global;
renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
{
    { "ASP.NET_SessionId", sessionId }
};

foreach (var id in invoiceIds)
{
    renderer.RenderUrlAsPdf($"https://app.example.com/invoices/{id}")
            .SaveAs($"invoice-{id}.pdf");
}

Imports IronPdf.Rendering

Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.RequestContext = RequestContexts.Global
renderer.RenderingOptions.CustomCookies = New Dictionary(Of String, String) From {
    {"ASP.NET_SessionId", sessionId}
}

For Each id In invoiceIds
    renderer.RenderUrlAsPdf($"https://app.example.com/invoices/{id}").SaveAs($"invoice-{id}.pdf")
Next

Imports IronPdf.Rendering

Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.RequestContext = RequestContexts.Global
renderer.RenderingOptions.CustomCookies = New Dictionary(Of String, String) From {
    {"ASP.NET_SessionId", sessionId}
}

For Each id In invoiceIds
    renderer.RenderUrlAsPdf($"https://app.example.com/invoices/{id}").SaveAs($"invoice-{id}.pdf")
Next

O cenário oposto tem tanto peso quanto. Um serviço que renderiza para muitos usuários diferentes ao mesmo tempo precisa de contexto Isolated, que dá a cada renderização um estado limpo e impede que a sessão de um usuário vaze para o documento de outro. Dê a cada thread seu próprio renderizador:

using System.Threading.Tasks;

Parallel.ForEach(jobs, job =>
{
    var renderer = new ChromePdfRenderer();
    renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Isolated;
    renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
    {
        { "ASP.NET_SessionId", job.SessionId }
    };

    renderer.RenderUrlAsPdf(job.Url).SaveAs(job.OutputPath);
});

using System.Threading.Tasks;

Parallel.ForEach(jobs, job =>
{
    var renderer = new ChromePdfRenderer();
    renderer.RenderingOptions.RequestContext = IronPdf.Rendering.RequestContexts.Isolated;
    renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
    {
        { "ASP.NET_SessionId", job.SessionId }
    };

    renderer.RenderUrlAsPdf(job.Url).SaveAs(job.OutputPath);
});

Imports System.Threading.Tasks
Imports IronPdf.Rendering

Parallel.ForEach(jobs, Sub(job)
    Dim renderer = New ChromePdfRenderer()
    renderer.RenderingOptions.RequestContext = RequestContexts.Isolated
    renderer.RenderingOptions.CustomCookies = New Dictionary(Of String, String) From {
        {"ASP.NET_SessionId", job.SessionId}
    }

    renderer.RenderUrlAsPdf(job.Url).SaveAs(job.OutputPath)
End Sub)

Imports System.Threading.Tasks
Imports IronPdf.Rendering

Parallel.ForEach(jobs, Sub(job)
    Dim renderer = New ChromePdfRenderer()
    renderer.RenderingOptions.RequestContext = RequestContexts.Isolated
    renderer.RenderingOptions.CustomCookies = New Dictionary(Of String, String) From {
        {"ASP.NET_SessionId", job.SessionId}
    }

    renderer.RenderUrlAsPdf(job.Url).SaveAs(job.OutputPath)
End Sub)

Ajustando o método ao trabalho

Use cookies padrão (ApplyCookies) para autenticação HTTP básica, autenticação do Windows e sessões simples. Use CustomCookies com tokens, sessões de múltiplos parâmetros, provedores terceiros e preferências armazenadas. Escolha Global para compartilhar estado entre renderizações e Isolated para mantê-las separadas; Auto tem como padrão isolado e alterna para global uma vez que ApplyCookies é chamado.

A maioria das falhas se agrupam em torno de tokens expirados, domínios de cookies desajustados, manuseio de cookies seguros em URLs HTTPS e políticas SameSite em solicitações de origem cruzada. Confirme a validade dos cookies antes de renderizar e utilize Global quando as sessões precisarem persistir.

Quando cookies são todo o trabalho

Cookies não são um caso extremo na geração de PDF. Acertem e você entrega um documento utilizável; erram e você entrega uma captura de tela de um formulário de login.

Curtis Chau

Converse agora mesmo com a equipe de engenharia.

Redator Técnico

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

...