Como Configurar Servidores Proxy para Renderização de PDFs em C

Fluxo de Trabalho Mínimo (3 Etapas)

1. Instale o IronPDF via NuGet: Install-Package IronPdf
2. Passe a string proxy como terceiro parâmetro para RenderHtmlAsPdf
3. Formato: http(s)://host:port ou http(s)://user:pass@host:port para proxies autenticados

Como passar um proxy para RenderHtmlAsPdf?

O parâmetro Proxy é um string opcional em quatro assinaturas de método:

// Instance methods
PdfDocument RenderHtmlAsPdf(string Html, string BaseUrlOrPath, string Proxy = null)
PdfDocument RenderHtmlAsPdf(string Html, Uri BaseUrl = null, string Proxy = null)

// Static methods
PdfDocument StaticRenderHtmlAsPdf(string Html, ChromePdfRenderOptions Options = null, string Proxy = null)
PdfDocument StaticRenderHtmlAsPdf(string Html, string BaseUrlOrPath, ChromePdfRenderOptions Options = null, string Proxy = null)

// Instance methods
PdfDocument RenderHtmlAsPdf(string Html, string BaseUrlOrPath, string Proxy = null)
PdfDocument RenderHtmlAsPdf(string Html, Uri BaseUrl = null, string Proxy = null)

// Static methods
PdfDocument StaticRenderHtmlAsPdf(string Html, ChromePdfRenderOptions Options = null, string Proxy = null)
PdfDocument StaticRenderHtmlAsPdf(string Html, string BaseUrlOrPath, ChromePdfRenderOptions Options = null, string Proxy = null)

' Instance methods
Function RenderHtmlAsPdf(Html As String, BaseUrlOrPath As String, Optional Proxy As String = Nothing) As PdfDocument
End Function

Function RenderHtmlAsPdf(Html As String, Optional BaseUrl As Uri = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

' Static methods
Shared Function StaticRenderHtmlAsPdf(Html As String, Optional Options As ChromePdfRenderOptions = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

Shared Function StaticRenderHtmlAsPdf(Html As String, BaseUrlOrPath As String, Optional Options As ChromePdfRenderOptions = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

Quando este parâmetro é null (o padrão), o mecanismo Chromium do IronPDF se conecta diretamente a recursos externos — folhas de estilo, imagens, fontes e arquivos JavaScript referenciados no seu HTML. Quando você fornece uma string de proxy, todas as solicitações HTTP/HTTPS do mecanismo de renderização passam por esse proxy.

using IronPdf;

var renderer = new ChromePdfRenderer();

// Direct connection (default — no proxy)
var pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>");

// Through an unauthenticated proxy
var pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath: null,
    proxy: "http://squid.internal:3128"
);

// Using the Uri overload
var pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl: new Uri("https://assets.example.com/"),
    proxy: "https://proxy.corp.local:8443"
);

using IronPdf;

var renderer = new ChromePdfRenderer();

// Direct connection (default — no proxy)
var pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>");

// Through an unauthenticated proxy
var pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath: null,
    proxy: "http://squid.internal:3128"
);

// Using the Uri overload
var pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl: new Uri("https://assets.example.com/"),
    proxy: "https://proxy.corp.local:8443"
);

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

' Direct connection (default — no proxy)
Dim pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>")

' Through an unauthenticated proxy
Dim pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath:=Nothing,
    proxy:="http://squid.internal:3128"
)

' Using the Uri overload
Dim pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl:=New Uri("https://assets.example.com/"),
    proxy:="https://proxy.corp.local:8443"
)

A string de proxy suporta os esquemas http:// e https://. Use https:// quando o próprio proxy exigir criptografia TLS para a conexão entre seu aplicativo e o servidor proxy. O esquema aqui se refere à conexão proxy, não ao recurso final — um proxy http:// ainda pode buscar recursos https:// por meio de tunelamento CONNECT.

As variantes do método estático aceitam o mesmo parâmetro de proxy, o que é útil para renderizações pontuais em aplicativos de console ou testes de unidade:

// Static render with proxy — no renderer instance needed
var pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options: null,
    proxy: "http://proxy.corp.local:8080"
);

// Static render with proxy — no renderer instance needed
var pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options: null,
    proxy: "http://proxy.corp.local:8080"
);

' Static render with proxy — no renderer instance needed
Dim pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options:=Nothing,
    proxy:="http://proxy.corp.local:8080"
)

Importante : Não existe a propriedade Proxy em ChromePdfRenderOptions. Não procure por isso lá. O proxy é estritamente um parâmetro de método nas sobrecargas RenderHtmlAsPdf e FromHtml.

Como Autenticar com um Proxy Corporativo?

A maioria dos proxies empresariais exige credenciais. Você os incorpora diretamente no URL do proxy usando o formato http(s)://username:password@host:port:

using IronPdf;

var renderer = new ChromePdfRenderer();

string proxyWithAuth = "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080";

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: @"C:\templates\assets\",
    proxy: proxyWithAuth
);
pdf.SaveAs("report.pdf");

using IronPdf;

var renderer = new ChromePdfRenderer();

string proxyWithAuth = "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080";

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: @"C:\templates\assets\",
    proxy: proxyWithAuth
);
pdf.SaveAs("report.pdf");

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

Dim proxyWithAuth As String = "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"

Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: "C:\templates\assets\",
    proxy:=proxyWithAuth
)
pdf.SaveAs("report.pdf")

Codifique os caracteres especiais em senhas usando a codificação URL. Se sua senha contiver @, #, :, / ou outros caracteres URI reservados, eles deverão ser codificados em porcentagem. Codificações comuns:

Use Uri.EscapeDataString() para codificar a senha programaticamente:

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.corp.local:8080";

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.corp.local:8080";

Imports System

Dim rawPassword As String = "P@ssw0rd!"
Dim encoded As String = Uri.EscapeDataString(rawPassword) ' "P%40ssw0rd%21"
Dim proxy As String = $"http://svc-account:{encoded}@proxy.corp.local:8080"

Não confunda autenticação por proxy com autenticação de página web. As propriedades ChromeHttpLoginCredentials.NetworkUsername e NetworkPassword autenticam a página web que está sendo renderizada (NTLM/Negociar com um site), não um servidor proxy. Para autenticação de proxy, as credenciais vão na string da URL do proxy conforme mostrado acima.

Como Renderizar URLs por Trás de um Proxy?

RenderUrlToPdf não aceita um parâmetro proxy. Essa é uma escolha deliberada de design da API — NavigateUrl navega o Chromium para um URL, e a configuração de proxy para essa navegação é tratada de forma diferente do carregamento de recursos durante a renderização de HTML.

A solução alternativa recomendada: busque o HTML você mesmo usando HttpClient configurado com um HttpProxy, e então passe a string HTML para RenderHtmlAsPdf com o parâmetro proxy (para que os recursos referenciados — imagens, CSS, fontes — também sejam roteados através do proxy).

using IronPdf;
using System.Net;
using System.Net.Http;

// Step 1: Configure HttpClient with the corporate proxy
var proxy = new WebProxy("http://proxy.corp.local:8080")
{
    Credentials = new NetworkCredential("svc-account", "P@ssw0rd!")
};

var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var httpClient = new HttpClient(handler);

// Step 2: Fetch the HTML from the target URL
string targetUrl = "https://dashboard.internal.corp/quarterly-report";
string html = await httpClient.GetStringAsync(targetUrl);

// Step 3: Render the fetched HTML, with the proxy for asset loading
var renderer = new ChromePdfRenderer();

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    html,
    baseUrlOrPath: targetUrl,  // Resolves relative asset paths against the original URL
    proxy: "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"
);
pdf.SaveAs("quarterly-report.pdf");

using IronPdf;
using System.Net;
using System.Net.Http;

// Step 1: Configure HttpClient with the corporate proxy
var proxy = new WebProxy("http://proxy.corp.local:8080")
{
    Credentials = new NetworkCredential("svc-account", "P@ssw0rd!")
};

var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var httpClient = new HttpClient(handler);

// Step 2: Fetch the HTML from the target URL
string targetUrl = "https://dashboard.internal.corp/quarterly-report";
string html = await httpClient.GetStringAsync(targetUrl);

// Step 3: Render the fetched HTML, with the proxy for asset loading
var renderer = new ChromePdfRenderer();

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    html,
    baseUrlOrPath: targetUrl,  // Resolves relative asset paths against the original URL
    proxy: "http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"
);
pdf.SaveAs("quarterly-report.pdf");

Imports IronPdf
Imports System.Net
Imports System.Net.Http

' Step 1: Configure HttpClient with the corporate proxy
Dim proxy As New WebProxy("http://proxy.corp.local:8080") With {
    .Credentials = New NetworkCredential("svc-account", "P@ssw0rd!")
}

Dim handler As New HttpClientHandler With {.Proxy = proxy, .UseProxy = True}
Using httpClient As New HttpClient(handler)
    ' Step 2: Fetch the HTML from the target URL
    Dim targetUrl As String = "https://dashboard.internal.corp/quarterly-report"
    Dim html As String = Await httpClient.GetStringAsync(targetUrl)

    ' Step 3: Render the fetched HTML, with the proxy for asset loading
    Dim renderer As New ChromePdfRenderer()

    Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(
        html,
        baseUrlOrPath:=targetUrl,  ' Resolves relative asset paths against the original URL
        proxy:="http://svc-account:P%40ssw0rd%21@proxy.corp.local:8080"
    )
    pdf.SaveAs("quarterly-report.pdf")
End Using

O parâmetro baseUrlOrPath é definido com o URL de destino original para que os caminhos relativos no HTML obtido (<img src="/images/logo.png">, <link href="/css/styles.css">) sejam resolvidos corretamente. O parâmetro proxy garante que essas solicitações de recursos sejam roteadas pelo proxy durante a renderização.

Esse padrão também funciona com páginas protegidas por autenticação — configure o HttpClient com os cookies ou cabeçalhos apropriados antes de buscar, e então passe o HTML autenticado para o IronPDF. O guia de cabeçalho de requisição HTTP cobre a configuração de cabeçalhos para solicitações autenticadas.

Se a página depender de JavaScript para renderização (SPAs, painéis React, aplicativos Angular), o HTML obtido conterá apenas a estrutura inicial — a renderização do lado do cliente não será executada durante a busca. Para esses casos, você tem duas opções: definir variáveis ​​de ambiente de nível de sistema HTTPS_PROXY (abordadas na próxima seção) para que RenderUrlAsPdf() roteie através do proxy no nível do SO, ou usar um navegador sem interface gráfica para buscar o HTML totalmente renderizado antes de passá-lo para RenderHtmlAsPdf().

Como Configurar Proxy em Contêineres Docker?

Em ambientes containerizados, você pode preferir a configuração de proxy a nível de sistema sobre parâmetros por método. O mecanismo Chromium do IronPDF respeita as variáveis ​​de ambiente padrão HTTP_PROXY e HTTPS_PROXY que os contêineres Linux usam para roteamento de tráfego de saída.

Defina estes no seu Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:8.0

# System-level proxy for all outbound HTTP/HTTPS traffic
ENV HTTP_PROXY=http://proxy.corp.local:8080
ENV HTTPS_PROXY=http://proxy.corp.local:8080
ENV NO_PROXY=localhost,127.0.0.1,.internal.corp

# Install IronPDF dependencies (fonts, etc.)
RUN apt-get update && apt-get install -y \
    libgdiplus \
    libc6-dev \
    fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

Com essas variáveis ​​de ambiente definidas, você pode chamar RenderHtmlAsPdf sem o parâmetro proxy — o Chromium detecta automaticamente a configuração do sistema:

// No proxy parameter needed — Chromium uses HTTP_PROXY env var
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);

// No proxy parameter needed — Chromium uses HTTP_PROXY env var
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);

' No proxy parameter needed — Chromium uses HTTP_PROXY env var
Dim renderer As New ChromePdfRenderer()
Dim pdf = renderer.RenderHtmlAsPdf(htmlContent)

RenderHtmlAsPdf() é importante para recursos internos. Sem isso, solicitações para serviços internos (como um servidor CSS local ou CDN de imagens rodando dentro do seu cluster Kubernetes) seriam desnecessariamente roteadas através do proxy. Separe por vírgula os nomes de host e domínios que devem ignorar o proxy.

Se você precisar de um proxy a nível de sistema para tráfego geral e um proxy diferente para renderizações específicas, o parâmetro de método sobrepõe a configuração da variável de ambiente. Isso lhe dá controle por renderização quando necessário.

Como Lidar com Proxy em Pipelines CI/CD?

Runners CI/CD em redes corporativas frequentemente estão por trás de proxies. Passe a URL do proxy como uma variável de build ou segredo — nunca codifique credenciais no controle de versão.

Ações GitHub:

jobs:
  generate-pdf:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{ secrets.CORP_PROXY_URL }}
      HTTPS_PROXY: ${{ secrets.CORP_PROXY_URL }}
    steps:
      - uses: actions/checkout@v4
      - run: dotnet build
      - run: dotnet test

jobs:
  generate-pdf:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{ secrets.CORP_PROXY_URL }}
      HTTPS_PROXY: ${{ secrets.CORP_PROXY_URL }}
    steps:
      - uses: actions/checkout@v4
      - run: dotnet build
      - run: dotnet test

Azure DevOps:

variables:
  - group: proxy-settings  # Contains PROXY_URL secret

steps:
  - script: |
      export HTTP_PROXY=$(PROXY_URL)
      export HTTPS_PROXY=$(PROXY_URL)
      dotnet run --project PdfGenerator
    displayName: 'Generate PDFs behind proxy'

variables:
  - group: proxy-settings  # Contains PROXY_URL secret

steps:
  - script: |
      export HTTP_PROXY=$(PROXY_URL)
      export HTTPS_PROXY=$(PROXY_URL)
      dotnet run --project PdfGenerator
    displayName: 'Generate PDFs behind proxy'

Jenkins (Pipeline Declarativo):

environment {
    HTTP_PROXY  = credentials('corp-proxy-url')
    HTTPS_PROXY = credentials('corp-proxy-url')
}

Em todos os três casos, o Chromium lê as variáveis de ambiente automaticamente. Se você preferir controle explícito, leia a URL do proxy a partir do ambiente e passe como parâmetro de método:

string? proxy = Environment.GetEnvironmentVariable("HTTPS_PROXY");
var pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath: null, proxy: proxy);

string? proxy = Environment.GetEnvironmentVariable("HTTPS_PROXY");
var pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath: null, proxy: proxy);

Option Strict On



Dim proxy As String = Environment.GetEnvironmentVariable("HTTPS_PROXY")
Dim pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath:=Nothing, proxy:=proxy)

Como Solucionar Problemas de Proxy?

Erros de tempo limite: Proxies corporativos adicionam latência. Aumente o tempo limite de renderização do padrão de 60 segundos:

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120 ' seconds

Esta é a propriedade RenderTimeout — ela controla por quanto tempo o Chromium espera pelo carregamento da página e pela busca de recursos combinados. Se o seu proxy adiciona 5–10 segundos de latência por solicitação, e a página carrega mais de 20 recursos externos, 60 segundos podem não ser suficientes.

Interceptação SSL (proxies MITM): Muitos proxies corporativos descriptografam e recriptografam o tráfego HTTPS usando um certificado CA root corporativo. O Chromium rejeita essas conexões porque não confia na CA corporativa por padrão. Duas soluções:

1. Instale o certificado CA corporativo no repositório root confiável do contêiner ou do host. No Linux: copie o .crt para /usr/local/share/ca-certificates/ e execute update-ca-certificates.
2. Somente em desenvolvimento, você pode desativar a validação de certificados — mas nunca faça isso em produção. A abordagem mais segura é sempre instalar o certificado correto.

Autenticação NTLM : O formato embutido user:pass@host suporta autenticação de proxy básica e Digest. NTLM (comum em empresas centradas em Windows) não é suportado através da string de URL do proxy. A solução alternativa é executar um proxy de redirecionamento NTLM-para-Basic local como o CNTLM no host ou como um contêiner sidecar. Configure o CNTLM com suas credenciais NTLM e, em seguida, aponte o IronPDF para http://localhost:3128 (a porta padrão do CNTLM).

PDF em branco ou recursos ausentes: Se o PDF é renderizado mas as imagens/CSS estão ausentes, seu HTML refere recursos que o proxy bloqueia ou que requerem um caminho de proxy diferente. Verifique se o parâmetro baseUrlOrPath é resolvido corretamente pelo proxy e consulte os logs de acesso do proxy em busca de respostas 403 ou 407.

Ignorar proxy para recursos locais: Se seu HTML refere uma mistura de recursos locais (imagens empacotadas, CSS incorporado) e recursos remotos (fontes CDN, scripts externos), o proxy apenas precisa lidar com as solicitações remotas. Configure baseUrlOrPath para um diretório local para ativos do sistema de arquivos e deixe o proxy lidar apenas com as solicitações de rede. Isso evita que leituras de arquivos locais passem desnecessariamente pelo proxy.

Diagnóstico de conectividade : Para verificar se sua string de proxy está correta antes de usá-la com o IronPDF, teste-a primeiro com uma solicitação simples HttpClient:

var proxy = new WebProxy("http://proxy.corp.local:8080");
var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var client = new HttpClient(handler);

var response = await client.GetAsync("https://httpbin.org/ip");
Console.WriteLine(await response.Content.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP

var proxy = new WebProxy("http://proxy.corp.local:8080");
var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var client = new HttpClient(handler);

var response = await client.GetAsync("https://httpbin.org/ip");
Console.WriteLine(await response.Content.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP

Imports System
Imports System.Net
Imports System.Net.Http

Dim proxy As New WebProxy("http://proxy.corp.local:8080")
Dim handler As New HttpClientHandler With {.Proxy = proxy, .UseProxy = True}
Using client As New HttpClient(handler)
    Dim response = Await client.GetAsync("https://httpbin.org/ip")
    Console.WriteLine(Await response.Content.ReadAsStringAsync())
    ' Should return the proxy's external IP, not your machine's IP
End Using

Se isso tiver sucesso mas o IronPDF ainda falhar, a questão é provavelmente a interceptação SSL ou um descompasso de protocolo entre o seu proxy e o tunelamento CONNECT do Chromium. Verifique se o proxy suporta CONNECT HTTP para recursos HTTPS — alguns proxies exigem configuração explícita para permitir tunelamento.

Próximos passos