PDF İşleme için Proxy Sunucularını C# ile Nasıl Yapılandırırım?

Minimal İş Akışı (3 Adım)

1. IronPDF'yi NuGet aracılığıyla kurun: Install-Package IronPdf
2. Proxy dizgesini RenderHtmlAsPdf'ın üçüncü parametresi olarak geçirin
3. Kimlik doğrulamalı proxy'ler için format: http(s)://host:port veya http(s)://user:pass@host:port

RenderHtmlAsPdf için bir Proxy Nasıl Geçirilir?

Proxy parametresi dört metod imzasında isteğe bağlı bir string'dir:

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

Bu parametre null (varsayılan) olduğunda, IronPDF'nin Chromium motoru dış kaynaklara doğrudan bağlanır: stil sayfaları, resimler, yazı tipleri ve HTML'nizdeki JavaScript dosyaları referans edilir. Bir proxy dizgesi sağladığınızda, işleme motorundan yapılan tüm HTTP/HTTPS istekleri o proxy üzerinden yönlendirilir.

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

Proxy dizgesi hem http:// hem de https:// şemalarını destekler. Proxy'nin kendisi bağlantı için proxy sunucusu ile uygulamanız arasındaki TLS şifrelemesini gerektirdiğinde https:// kullanın. Buradaki şema son kaynak ile ilgili değil, proxy bağlantısına aittir — bir http:// proxy yine de CONNECT tünellendirme aracılığıyla https:// kaynakları alabilir.

Statik yöntem varyantları aynı proxy parametresini kabul eder, bu da konsol uygulamalarında veya birim testlerinde tek seferlik işleme için yararlıdır:

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

Önemli: Proxy özelliği ChromePdfRenderOptions üzerinde yoktur. Orada aramayın. Proxy kesinlikle RenderHtmlAsPdf ve FromHtml yüklemeleri üzerinde bir metod parametresidir.

Kurumsal Proxy ile Nasıl Kimlik Doğrulama Yapılır?

Çoğu kurumsal proxy kimlik bilgileri gerektirir. Onları doğrudan proxy URL'sine http(s)://username:password@host:port formatında yerleştirin:

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

Parolalardaki özel karakterleri URL kodlayın. Parolanız @, #, :, / veya diğer önceden ayrılmış URI karakterlerini içeriyorsa, bunlar yüzde kodlaması yapılmalıdır. Yaygın kodlamalar:

Parolayı programlı olarak kodlamak için Uri.EscapeDataString() kullanın:

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

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.co/rp.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.co/rp.local:8080"

Proxy kimlik doğrulamasını web sayfası kimlik doğrulaması ile karıştırmayın. ChromeHttpLoginCredentials.NetworkUsername ve NetworkPassword özellikleri (NTLM/Negotiate ile bir web sitesi), oluşturulmakta olan web sayfasına karşı kimlik doğrulaması yapar, proxy sunucusuna karşı değil. Proxy kimlik doğrulaması için, kimlik bilgileri yukarıda gösterildiği gibi proxy URL dizgesine girilmelidir.

Bu türden favori kütüphanem IronPDF'dir. PDF dosyalarının hızlı ve verimli bir şekilde işlenmesine olanak tanır. Ayrıca, PDF/A formatına dışa aktarma ve dijital imzalama gibi birçok değerli özelliğe sahiptir.

Milan Jovanovic

Microsoft MVP

Vaka çalışmasını görüntüle

IronOCR, manuel işleme maliyetinden yıllık 40.000 USD tasarruf etmemizi sağlıyor, üretkenliği artırıyor ve yüksek etkili görevler için kaynakları serbest bırakıyor. Kesinlikle tavsiye ederim.

Brent Matzelle

Teknoloji Müdürü, OPYN

Vaka çalışmasını görüntüle

IronSuite, operasyonlarımızda kritik bir rol oynar. Bunlar, iş süreçlerinde verimliliği artıran, kat planları oluşturmak ve envanter yönetimini geliştirmek gibi araçlardır.

David Jones

Baş Yazılım Mühendisi, Agorus Build

Vaka çalışmasını görüntüle

Proxy Arkasındaki URL'ler Nasıl İşlenir?

RenderUrlToPdf bir proxy parametresini kabul etmez. Bu kasıtlı bir API tasarım tercihi — NavigateUrl Chromium'u bir URL'ye yönlendirir ve bu yönlendirme için proxy yapılandırması HTML işleme sırasında kaynak yüklemeden farklı şekilde ele alınır.

Önerilen geçici çözüm: HTML'yi kendiniz HttpClient ile yapılandırılmış bir HttpProxy ile alın, ardından HTML dizgesini proxy parametresi ile RenderHtmlAsPdf'a geçirin (böylece referans verilen varlıklar — resimler, CSS, yazı tipleri — de proxy üzerinden yönlendirilir).

: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

baseUrlOrPath parametresi, eğer alınan HTML'deki göreceli yollar (<img src="/images/logo.png">, <link href="/css/styles.css">) doğru bir şekilde çözülmesi için orijinal hedef URL'ye ayarlanmıştır. proxy parametresi, bu varlık isteklerinin işleme sırasında proxy üzerinden yönlendirilmesini garanti eder.

Bu model kimlik doğrulaması arkasındaki sayfalarla da çalışır — almadan önce uygun çerezler veya başlıklar ile HttpClient yapılandırın, ardından kimlik doğrulamalı HTML'yi IronPDF'ye aktarın. HTTP istek başlığı nasıl yapılır, kimlik doğrulamalı istekler için başlık yapılandırmasını kapsar.

Sayfa JavaScript'e dayalıysa (SPAs, React kontrol panelleri, Angular uygulamaları), alınan HTML yalnızca ilk kabuğu içerecektir — istemci tarafı render HttpClient alma sırasında çalışmayacaktır. Bu durumlarda, iki seçeneğiniz var: sistem seviyesi HTTPS_PROXY ortam değişkenlerini ayarlayın (bir sonraki bölümde ele alınacak) böylece RenderUrlAsPdf() işletim sistemi seviyesinde proxy üzerinden yönlendirir, veya tam işlemi tamamlanmış HTML'yi almak için başsız bir tarayıcı kullanın ve RenderHtmlAsPdf()'a geçirin.

Docker Konteynerlerinde Proxy Nasıl Yapılandırılır?

Konteynerleştirilmiş ortamlarda, yöntem başına parametreler yerine sistem düzeyinde proxy yapılandırmasını tercih edebilirsiniz. IronPDF'nin Chromium motoru, Linux konteynerlerinin dış trafik yönlendirmesi için kullandığı standart HTTP_PROXY ve HTTPS_PROXY ortam değişkenlerine saygı duyar.

Bunları Dockerfile'ınızda ayarlayın:

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

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

# 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"]

Bu ortam değişkenleri ayarlandığında, RenderHtmlAsPdf çağırabilirsiniz — proksi parametresi olmadan, Chromium sistem seviyesindeki yapılandırmayı otomatik olarak alır:

: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() dahili kaynaklar için önemlidir. Olmadan, iç hizmetlere (örneğin, Kubernetes kümeniz içinde çalışan yerel bir CSS sunucusu veya resim CDN'ine yapılan istekler) gereksiz yere proxy üzerinden yönlendirilir. Proxy'i atlaması gereken ana bilgisayar adlarını ve alan adlarını virgülle ayırın.

Genel trafik için sistem düzeyinde proxy ve belirli işleme için farklı bir proxy ihtiyacınız varsa, yöntem parametresi ortam değişkeni üzerinde önceliklidir. Gerekli olduğunda, işleme başına kontrol sağlar.

CI/CD Pipelines İçinde Proxy Nasıl Ele Alınır?

Kurumsal ağlardaki CI/CD yürütücüleri genellikle proxy'lerin arkasında bulunur. Proxy URL'sini bir yapı değişkeni veya gizli olarak geçirin — kimlik bilgilerini kaynak kontrolünde asla sert kodlamayın.

GitHub Eylemleri:

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 (Deklaratif Pipeline):

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

Üç durumda da Chromium, ortam değişkenlerini otomatik olarak okur. Açık kontrolü tercih ederseniz, proxy URL'sini ortamdan okuyun ve yöntem parametresi olarak geçirin:

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

Proxy Sorunları Nasıl Giderilir?

Zaman aşımı hataları: Kurumsal proxy'ler gecikme ekler. 60 saniyelik varsayılandan işleme zaman aşımını artırın:

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120 ' seconds

Bu, RenderTimeout özelliğidir — Chromium'un sayfa yükleme ve kaynak alma birleşimi için ne kadar bekleyeceğini kontrol eder. Proxy'niz her istekte 5-10 saniyelik gecikme ekliyorsa ve sayfa 20+ dış kaynağı yüklüyorsa, 60 saniye yeterli olmaz.

SSL engellemesi (MITM proxy'ler): Birçok kurumsal proxy, HTTPS trafiğini kurumsal kök CA sertifikası kullanarak şifreler ve çözer. Chromium, varsayılan olarak kurumsal CA'ya güvenmediği için bu bağlantıları reddeder. İki çözüm:

1. Kurumsal CA sertifikasını konteyner veya ana sunucunun güvenilir kök deposuna yükleyin. Linux'ta: .crt'yı /usr/local/share/ca-certificates/'a kopyalayın ve update-ca-certificates çalıştırın.
2. Sadece geliştirme sırasında, sertifika doğrulamasını devre dışı bırakabilirsiniz — ancak bunu üretim ortamında asla yapmayın. Daha güvenli yaklaşım, doğru sertifikayı yüklemektir.

NTLM kimlik doğrulaması: Satır içi user:pass@host formatı Basic ve Digest proxy kimlik doğrulamasını destekler. NTLM (Windows odaklı işletmelerde yaygın) proxy URL dizesi aracılığıyla desteklenmez. Geçici çözüm, ana bilgisayarda veya bir yan araç konteynerinde CNTLM gibi yerel bir NTLM-o-Basic iletici proxy işletmektir. NTLM kimlik bilgileri ile CNTLM'yi yapılandırın, ardından IronPDF'yi http://localhost:3128 (CNTLM'nin varsayılan portu) üzerine yönlendirin.

Boş PDF veya eksik varlıklar: PDF işleniyorsa ancak resimler/CSS eksikse, HTML'niz proxy'nin engellediği veya farklı bir proxy yolu gerektiren kaynaklara referans veriyor olabilir. baseUrlOrPath parametresinin proxy üzerinden doğru bir şekilde çözüldüğünden ve proxy'nin erişim loglarında 403 veya 407 yanıtlarının kontrol edildiğinden emin olun.

Yerel varlıklar için proxy atlama: HTML'niz yerel varlıklara (paketlenmiş resimler, satır içi CSS) ve uzak kaynaklara (CDN yazı tipleri, harici betikler) referans veriyorsa, proxy yalnızca uzak istekleri işlemesi gerek. baseUrlOrPath'yi dosya sistemi varlıkları için yerel bir dizine ayarlayın ve yalnızca ağ isteklerini proxy'nin halletmesine izin verin. Bu, yerel dosya okumalarını gereksiz yere proxy üzerinden yönlendirmeyi önler.

Bağlanabilirliği teşhis etme: Proxy dizginizin IronPDF ile kullanmadan önce doğru olup olmadığını doğrulamak için, önce basit bir HttpClient isteğiyle test edin:

var proxy = new WebProxy("http://proxy.co/rp.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.co/rp.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.Net.Http
Imports System.Net

Dim proxy As New WebProxy("http://proxy.co/rp.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

Bu başarıya ulaşırsa ancak IronPDF hala başarısız oluyorsa, sorun muhtemelen SSL durdurması veya proxy ile Chromium'un CONNECT tünelleme arasındaki protokol uyumsuzluğudur. Proxy'nin HTTPS kaynakları için HTTP CONNECT'i destekleyip desteklemediğini kontrol edin — bazı proxy'ler tünellemeye izin vermek için açık bir yapılandırma gerektirir.

Sonraki Adımlar