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

Fluxo de Trabalho Mínimo (3 Etapas)

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

Como você passa 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 motor Chromium do IronPDF se conecta diretamente a recursos externos — folhas de estilo, imagens, fontes e arquivos JavaScript referenciados em seu HTML. Quando você fornece uma string de proxy, todas as solicitações HTTP/HTTPS do mecanismo de renderização passam por esse proxy.

:path=/static-assets/pdf/content-code-examples/how-to/proxy-3.cs

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 do proxy suporta ambos 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 refere-se à conexão do proxy, não ao recurso final — um proxy http:// ainda pode buscar recursos https:// via 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:

:path=/static-assets/pdf/content-code-examples/how-to/proxy-4.cs

// 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 há propriedade Proxy em ChromePdfRenderOptions. Não procure por isso lá. O proxy é estritamente um parâmetro de método em sobrecargas RenderHtmlAsPdf e FromHtml.

Como Autenticar com um Proxy Corporativo?

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

:path=/static-assets/pdf/content-code-examples/how-to/proxy-5.cs

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 caracteres especiais em senhas na URL. Se sua senha contiver @, #, :, /, ou outros caracteres reservados de URI, eles devem 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 de proxy com autenticação de página web. As propriedades ChromeHttpLoginCredentials.NetworkUsername e NetworkPassword autenticam-se contra a página web sendo renderizada (NTLM/Negotiate com um site), não contra um servidor proxy. Para autenticação de proxy, as credenciais vão na string da URL do proxy conforme mostrado acima.

Minha biblioteca favorita desse tipo é o IronPDF. Ele permite a manipulação rápida e eficiente de arquivos PDF. Além disso, possui muitos recursos valiosos, como a exportação para o formato PDF/A e a assinatura digital de documentos PDF.

Milan Jovanovic

Microsoft MVP

Veja o estudo de caso

Com o IronOCR, podemos economizar US$ 40.000 por ano em processamento manual, ao mesmo tempo que aumentamos a produtividade e liberamos recursos para tarefas de alto impacto. Eu o recomendo fortemente.

Brent Matzelle

Diretor de Tecnologia, OPYN

Veja o estudo de caso

O IronSuite desempenha um papel crucial nas nossas operações. Estas são ferramentas que aumentam a eficiência no negócio, incluindo a criação de plantas baixas e melhoria na gestão de inventário.

David Jones

Engenheiro(a) de Software Líder, Agorus Build

Veja o estudo de caso

Como Renderizar URLs por Trás de um Proxy?

RenderUrlToPdf não aceita um parâmetro de proxy. Esta é uma escolha deliberada de design da API — NavigateUrl navega 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 recomendada: recupere o HTML você mesmo usando HttpClient configurado com um HttpProxy, depois passe a string HTML para RenderHtmlAsPdf com o parâmetro de proxy (para que os ativos referenciados — imagens, CSS, fontes — também sejam roteados através do proxy).

:path=/static-assets/pdf/content-code-examples/how-to/proxy-7.cs

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 é configurado para o URL de destino original para que os caminhos relativos no HTML recuperado (<img src="/images/logo.png">, <link href="/css/styles.css">) sejam resolvidos corretamente. O parâmetro proxy garante que essas solicitações de ativos sejam roteadas através do proxy durante a renderização.

Esse padrão também funciona com páginas atrás de autenticação — configure o HttpClient com os cookies ou cabeçalhos apropriados antes de buscar, depois 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, dashboards React, aplicativos Angular), o HTML recuperado conterá apenas o shell inicial — a renderização no lado do cliente não será executada durante a recuperação HttpClient. Para esses casos, você tem duas opções: configure variáveis de ambiente HTTPS_PROXY em nível de sistema (cobertas na próxima seção) para que RenderUrlAsPdf() seja roteado através do proxy em nível de SO, ou use um navegador sem cabeça 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 motor Chromium do IronPDF respeita as variáveis de ambiente padrão HTTP_PROXY e HTTPS_PROXY que 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 configuradas, você pode chamar RenderHtmlAsPdf sem o parâmetro de proxy — o Chromium configura automaticamente a configuração em nível de sistema:

:path=/static-assets/pdf/content-code-examples/how-to/proxy-9.cs

// 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:

:path=/static-assets/pdf/content-code-examples/how-to/proxy-13.cs

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 quanto tempo o Chromium espera pelo carregamento da página e 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 inline user:pass@host suporta autenticação de proxy Básica e Digestiva. 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, depois aponte o IronPDF para http://localhost:3128 (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 através do proxy, e verifique os logs de acesso do proxy para 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.

Diagnosticando 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