Message icon
Skip to footer content
  1. IronPDF
  2. IronPDF Blog
  3. Migration Guides
  4. migration from webview2 to ironpdf
MIGRATION GUIDES

How to Migrate from WebView2 to IronPDF in C#

Curtis Chau
Curtis Chau
Updated:

WebView2, Microsoft's embeddable Edge/Chromium browser control, offers developers a way to display web content within Windows applications. However, when development teams attempt to use WebView2 for PDF generation, they encounter serious architectural limitations that make it unsuitable for production environments. WebView2 is a browser embedding control designed for UI applications—not a PDF generation library.

This guide provides a complete migration path from WebView2 to IronPDF, with step-by-step instructions, code comparisons, and practical examples for professional .NET developers who need reliable PDF generation in their applications.

Critical Warning: WebView2 Is NOT Suitable for PDF Generation

Before examining the migration path, development teams must understand why WebView2 creates significant problems when used for PDF creation:

Problem Impact Severity
Memory Leaks WebView2 has well-documented memory leaks in long-running processes. Your server will crash. CRITICAL
Windows-Only Zero support for Linux, macOS, Docker, or cloud environments CRITICAL
UI Thread Required Must run on STA thread with message pump. Cannot work in web servers or APIs. CRITICAL
Not Designed for PDFs PrintToPdfAsync is an afterthought, not a core feature HIGH
Unstable in Services Crashes and hangs common in Windows Services and background workers HIGH
Complex Async Flow Navigation events, completion callbacks, race conditions HIGH
Edge Runtime Dependency Requires Edge WebView2 Runtime installed on target machine MEDIUM
No Headless Mode Always creates UI elements even when hidden MEDIUM
Performance Slow startup, heavy resource consumption MEDIUM
No Professional Support Microsoft doesn't support PDF generation use case MEDIUM

Real-World Failure Scenarios

These code patterns cause production failures:

// DANGER: This code WILL cause problems in production

// Problem 1: Memory leak - creates new WebView2 for each PDF
public async Task<byte[]> GeneratePdf(string html) // Called 1000x/day = server crash
{
    using var webView = new WebView2(); // Memory not fully released!
    await webView.EnsureCoreWebView2Async();
    webView.CoreWebView2.NavigateToString(html);
    // ... memory accumulates until OOM
}

// Problem 2: UI thread requirement - crashes in ASP.NET
public IActionResult GenerateReport() // FAILS - no STA thread
{
    var webView = new WebView2(); // InvalidOperationException
}

// Problem 3: Windows Service instability
public class PdfService : BackgroundService // Random crashes
{
    protected override async Task ExecuteAsync(CancellationToken token)
    {
        // WebView2 + no message pump = hangs, crashes, undefined behavior
    }
}
// DANGER: This code WILL cause problems in production

// Problem 1: Memory leak - creates new WebView2 for each PDF
public async Task<byte[]> GeneratePdf(string html) // Called 1000x/day = server crash
{
    using var webView = new WebView2(); // Memory not fully released!
    await webView.EnsureCoreWebView2Async();
    webView.CoreWebView2.NavigateToString(html);
    // ... memory accumulates until OOM
}

// Problem 2: UI thread requirement - crashes in ASP.NET
public IActionResult GenerateReport() // FAILS - no STA thread
{
    var webView = new WebView2(); // InvalidOperationException
}

// Problem 3: Windows Service instability
public class PdfService : BackgroundService // Random crashes
{
    protected override async Task ExecuteAsync(CancellationToken token)
    {
        // WebView2 + no message pump = hangs, crashes, undefined behavior
    }
}
' DANGER: This code WILL cause problems in production

' Problem 1: Memory leak - creates new WebView2 for each PDF
Public Async Function GeneratePdf(html As String) As Task(Of Byte()) ' Called 1000x/day = server crash
    Using webView As New WebView2() ' Memory not fully released!
        Await webView.EnsureCoreWebView2Async()
        webView.CoreWebView2.NavigateToString(html)
        ' ... memory accumulates until OOM
    End Using
End Function

' Problem 2: UI thread requirement - crashes in ASP.NET
Public Function GenerateReport() As IActionResult ' FAILS - no STA thread
    Dim webView As New WebView2() ' InvalidOperationException
    ' Additional logic would go here
    Return Nothing ' Placeholder return
End Function

' Problem 3: Windows Service instability
Public Class PdfService
    Inherits BackgroundService ' Random crashes

    Protected Overrides Async Function ExecuteAsync(token As CancellationToken) As Task
        ' WebView2 + no message pump = hangs, crashes, undefined behavior
    End Function
End Class
$vbLabelText   $csharpLabel

IronPDF vs WebView2: Feature Comparison

Understanding the architectural differences helps technical decision-makers evaluate the migration investment:

Aspect WebView2 IronPDF
Purpose Browser control (UI) PDF library (designed for PDF)
Production Ready NO YES
Memory Management Leaks in long-running Stable, properly disposed
Platform Support Windows only Windows, Linux, macOS, Docker
Thread Requirements STA + Message Pump Any thread
Server/Cloud Not supported Supported
Azure/AWS/GCP Problematic Works perfectly
Docker Not possible Official images available
ASP.NET Core Cannot work First-class support
Background Services Unstable Stable
Supported Contexts WinForms/WPF only Any .NET context: console, web, desktop
HTML to PDF Basic Full
URL to PDF Basic Full
Headers/Footers NO Yes (HTML)
Watermarks NO Yes
Merge PDFs NO Yes
Split PDFs NO Yes
Digital Signatures NO Yes
Password Protection NO Yes
PDF/A Compliance NO Yes
Professional Support None for PDF Yes
Documentation Limited Extensive

Quick Start: WebView2 to IronPDF Migration

The migration can begin immediately with these foundational steps.

Step 1: Remove WebView2 Package

dotnet remove package Microsoft.Web.WebView2
dotnet remove package Microsoft.Web.WebView2
SHELL

Or remove from your project file:


<PackageReference Include="Microsoft.Web.WebView2" Version="*" Remove />

<PackageReference Include="Microsoft.Web.WebView2" Version="*" Remove />
XML

Step 2: Install IronPDF

dotnet add package IronPdf
dotnet add package IronPdf
SHELL

Step 3: Update Namespaces

Replace WebView2 namespaces with the IronPdf namespace:

// Before (WebView2)
using Microsoft.Web.WebView2.Core;
using Microsoft.Web.WebView2.WinForms;

// After (IronPDF)
using IronPdf;
// Before (WebView2)
using Microsoft.Web.WebView2.Core;
using Microsoft.Web.WebView2.WinForms;

// After (IronPDF)
using IronPdf;
Imports Microsoft.Web.WebView2.Core
Imports Microsoft.Web.WebView2.WinForms

' After (IronPDF)
Imports IronPdf
$vbLabelText   $csharpLabel

Step 4: Initialize License

Add license initialization at application startup:

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"
$vbLabelText   $csharpLabel

Code Migration Examples

Converting HTML to PDF

The most fundamental operation reveals the complexity difference between these .NET PDF approaches.

WebView2 Approach:

// NuGet: Install-Package Microsoft.Web.WebView2.WinForms
using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.Web.WebView2.WinForms;
using Microsoft.Web.WebView2.Core;

class Program
{
    static async Task Main()
    {
        var webView = new WebView2();
        await webView.EnsureCoreWebView2Async();

        webView.CoreWebView2.NavigateToString("<html><body><h1>Hello World</h1></body></html>");
        await Task.Delay(2000);

        await webView.CoreWebView2.CallDevToolsProtocolMethodAsync(
            "Page.printToPDF",
            "{}"
        );
    }
}
// NuGet: Install-Package Microsoft.Web.WebView2.WinForms
using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.Web.WebView2.WinForms;
using Microsoft.Web.WebView2.Core;

class Program
{
    static async Task Main()
    {
        var webView = new WebView2();
        await webView.EnsureCoreWebView2Async();

        webView.CoreWebView2.NavigateToString("<html><body><h1>Hello World</h1></body></html>");
        await Task.Delay(2000);

        await webView.CoreWebView2.CallDevToolsProtocolMethodAsync(
            "Page.printToPDF",
            "{}"
        );
    }
}
Imports System
Imports System.IO
Imports System.Threading.Tasks
Imports Microsoft.Web.WebView2.WinForms
Imports Microsoft.Web.WebView2.Core

Module Program
    Async Function Main() As Task
        Dim webView As New WebView2()
        Await webView.EnsureCoreWebView2Async()

        webView.CoreWebView2.NavigateToString("<html><body><h1>Hello World</h1></body></html>")
        Await Task.Delay(2000)

        Await webView.CoreWebView2.CallDevToolsProtocolMethodAsync(
            "Page.printToPDF",
            "{}"
        )
    End Function
End Module
$vbLabelText   $csharpLabel

IronPDF Approach:

// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<html><body><h1>Hello World</h1></body></html>");
        pdf.SaveAs("output.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<html><body><h1>Hello World</h1></body></html>");
        pdf.SaveAs("output.pdf");
    }
}
Imports IronPdf

Class Program
    Shared Sub Main()
        Dim renderer = New ChromePdfRenderer()
        Dim pdf = renderer.RenderHtmlAsPdf("<html><body><h1>Hello World</h1></body></html>")
        pdf.SaveAs("output.pdf")
    End Sub
End Class
$vbLabelText   $csharpLabel

The WebView2 version requires asynchronous initialization with EnsureCoreWebView2Async(), navigation via NavigateToString(), an unreliable Task.Delay(2000) to wait for rendering, and interaction with the DevTools Protocol. IronPDF eliminates this ceremony entirely—create a renderer, render HTML, save.

For advanced HTML-to-PDF scenarios, see the HTML to PDF conversion guide.

Converting URLs to PDF

URL-to-PDF conversion demonstrates WebView2's complex async navigation flow.

WebView2 Approach:

// NuGet: Install-Package Microsoft.Web.WebView2.WinForms
using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.Web.WebView2.WinForms;
using Microsoft.Web.WebView2.Core;

class Program
{
    static async Task Main()
    {
        var webView = new WebView2();
        await webView.EnsureCoreWebView2Async();

        var tcs = new TaskCompletionSource<bool>();
        webView.CoreWebView2.NavigationCompleted += (s, e) => tcs.SetResult(true);

        webView.CoreWebView2.Navigate("https://example.com");
        await tcs.Task;
        await Task.Delay(1000);

        var result = await webView.CoreWebView2.CallDevToolsProtocolMethodAsync(
            "Page.printToPDF",
            "{\"printBackground\": true}"
        );

        var base64 = System.Text.Json.JsonDocument.Parse(result).RootElement.GetProperty("data").GetString();
        File.WriteAllBytes("output.pdf", Convert.FromBase64String(base64));
    }
}
// NuGet: Install-Package Microsoft.Web.WebView2.WinForms
using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.Web.WebView2.WinForms;
using Microsoft.Web.WebView2.Core;

class Program
{
    static async Task Main()
    {
        var webView = new WebView2();
        await webView.EnsureCoreWebView2Async();

        var tcs = new TaskCompletionSource<bool>();
        webView.CoreWebView2.NavigationCompleted += (s, e) => tcs.SetResult(true);

        webView.CoreWebView2.Navigate("https://example.com");
        await tcs.Task;
        await Task.Delay(1000);

        var result = await webView.CoreWebView2.CallDevToolsProtocolMethodAsync(
            "Page.printToPDF",
            "{\"printBackground\": true}"
        );

        var base64 = System.Text.Json.JsonDocument.Parse(result).RootElement.GetProperty("data").GetString();
        File.WriteAllBytes("output.pdf", Convert.FromBase64String(base64));
    }
}
Imports System
Imports System.IO
Imports System.Threading.Tasks
Imports Microsoft.Web.WebView2.WinForms
Imports Microsoft.Web.WebView2.Core

Module Program
    Async Function Main() As Task
        Dim webView As New WebView2()
        Await webView.EnsureCoreWebView2Async()

        Dim tcs As New TaskCompletionSource(Of Boolean)()
        AddHandler webView.CoreWebView2.NavigationCompleted, Sub(s, e) tcs.SetResult(True)

        webView.CoreWebView2.Navigate("https://example.com")
        Await tcs.Task
        Await Task.Delay(1000)

        Dim result As String = Await webView.CoreWebView2.CallDevToolsProtocolMethodAsync(
            "Page.printToPDF",
            "{""printBackground"": true}"
        )

        Dim base64 As String = System.Text.Json.JsonDocument.Parse(result).RootElement.GetProperty("data").GetString()
        File.WriteAllBytes("output.pdf", Convert.FromBase64String(base64))
    End Function
End Module
$vbLabelText   $csharpLabel

IronPDF Approach:

// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderUrlAsPdf("https://example.com");
        pdf.SaveAs("output.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderUrlAsPdf("https://example.com");
        pdf.SaveAs("output.pdf");
    }
}
Imports IronPdf

Class Program
    Shared Sub Main()
        Dim renderer = New ChromePdfRenderer()
        Dim pdf = renderer.RenderUrlAsPdf("https://example.com")
        pdf.SaveAs("output.pdf")
    End Sub
End Class
$vbLabelText   $csharpLabel

WebView2 requires creating a TaskCompletionSource, subscribing to NavigationCompleted events, calling CallDevToolsProtocolMethodAsync, parsing JSON responses, and decoding base64 data. IronPDF provides a dedicated RenderUrlAsPdf method that handles all complexity internally.

Explore the URL to PDF documentation for authentication and custom header options.

Custom PDF Settings from HTML Files

Configuring page orientation, margins, and paper size requires different approaches.

WebView2 Approach:

// NuGet: Install-Package Microsoft.Web.WebView2.WinForms
using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.Web.WebView2.Core;
using Microsoft.Web.WebView2.WinForms;

class Program
{
    static async Task Main()
    {
        var webView = new WebView2();
        await webView.EnsureCoreWebView2Async();

        string htmlFile = Path.Combine(Directory.GetCurrentDirectory(), "input.html");
        webView.CoreWebView2.Navigate(htmlFile);

        await Task.Delay(3000);

        var printSettings = webView.CoreWebView2.Environment.CreatePrintSettings();
        printSettings.Orientation = CoreWebView2PrintOrientation.Landscape;
        printSettings.MarginTop = 0.5;
        printSettings.MarginBottom = 0.5;

        using (var stream = await webView.CoreWebView2.PrintToPdfAsync("custom.pdf", printSettings))
        {
            Console.WriteLine("Custom PDF created");
        }
    }
}
// NuGet: Install-Package Microsoft.Web.WebView2.WinForms
using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.Web.WebView2.Core;
using Microsoft.Web.WebView2.WinForms;

class Program
{
    static async Task Main()
    {
        var webView = new WebView2();
        await webView.EnsureCoreWebView2Async();

        string htmlFile = Path.Combine(Directory.GetCurrentDirectory(), "input.html");
        webView.CoreWebView2.Navigate(htmlFile);

        await Task.Delay(3000);

        var printSettings = webView.CoreWebView2.Environment.CreatePrintSettings();
        printSettings.Orientation = CoreWebView2PrintOrientation.Landscape;
        printSettings.MarginTop = 0.5;
        printSettings.MarginBottom = 0.5;

        using (var stream = await webView.CoreWebView2.PrintToPdfAsync("custom.pdf", printSettings))
        {
            Console.WriteLine("Custom PDF created");
        }
    }
}
Imports System
Imports System.IO
Imports System.Threading.Tasks
Imports Microsoft.Web.WebView2.Core
Imports Microsoft.Web.WebView2.WinForms

Module Program
    Async Function Main() As Task
        Dim webView As New WebView2()
        Await webView.EnsureCoreWebView2Async()

        Dim htmlFile As String = Path.Combine(Directory.GetCurrentDirectory(), "input.html")
        webView.CoreWebView2.Navigate(htmlFile)

        Await Task.Delay(3000)

        Dim printSettings = webView.CoreWebView2.Environment.CreatePrintSettings()
        printSettings.Orientation = CoreWebView2PrintOrientation.Landscape
        printSettings.MarginTop = 0.5
        printSettings.MarginBottom = 0.5

        Using stream = Await webView.CoreWebView2.PrintToPdfAsync("custom.pdf", printSettings)
            Console.WriteLine("Custom PDF created")
        End Using
    End Function
End Module
$vbLabelText   $csharpLabel

IronPDF Approach:

// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;
using System;
using System.IO;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();

        renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape;
        renderer.RenderingOptions.MarginTop = 50;
        renderer.RenderingOptions.MarginBottom = 50;

        string htmlFile = Path.Combine(Directory.GetCurrentDirectory(), "input.html");
        var pdf = renderer.RenderHtmlFileAsPdf(htmlFile);
        pdf.SaveAs("custom.pdf");

        Console.WriteLine("Custom PDF created");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;
using System;
using System.IO;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();

        renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape;
        renderer.RenderingOptions.MarginTop = 50;
        renderer.RenderingOptions.MarginBottom = 50;

        string htmlFile = Path.Combine(Directory.GetCurrentDirectory(), "input.html");
        var pdf = renderer.RenderHtmlFileAsPdf(htmlFile);
        pdf.SaveAs("custom.pdf");

        Console.WriteLine("Custom PDF created");
    }
}
Imports IronPdf
Imports IronPdf.Rendering
Imports System
Imports System.IO

Module Program
    Sub Main()
        Dim renderer As New ChromePdfRenderer()

        renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape
        renderer.RenderingOptions.MarginTop = 50
        renderer.RenderingOptions.MarginBottom = 50

        Dim htmlFile As String = Path.Combine(Directory.GetCurrentDirectory(), "input.html")
        Dim pdf = renderer.RenderHtmlFileAsPdf(htmlFile)
        pdf.SaveAs("custom.pdf")

        Console.WriteLine("Custom PDF created")
    End Sub
End Module
$vbLabelText   $csharpLabel

WebView2 requires a 3-second Task.Delay (an unreliable guess), creating print settings through the environment, and using PrintToPdfAsync with a stream. IronPDF provides direct RenderingOptions properties with clear names and uses millimeters for more precise measurements.

Advanced PDF Options with DevTools Protocol

Complex WebView2 configurations require DevTools Protocol interaction.

WebView2 Approach:

// NuGet: Install-Package Microsoft.Web.WebView2.WinForms
using System;
using System.IO;
using System.Threading.Tasks;
using System.Text.Json;
using Microsoft.Web.WebView2.WinForms;
using Microsoft.Web.WebView2.Core;

class Program
{
    static async Task Main()
    {
        var webView = new WebView2();
        await webView.EnsureCoreWebView2Async();

        var htmlPath = Path.GetFullPath("document.html");
        var tcs = new TaskCompletionSource<bool>();
        webView.CoreWebView2.NavigationCompleted += (s, e) => tcs.SetResult(true);

        webView.CoreWebView2.Navigate($"file:///{htmlPath}");
        await tcs.Task;
        await Task.Delay(1000);

        var options = new
        {
            landscape = false,
            printBackground = true,
            paperWidth = 8.5,
            paperHeight = 11,
            marginTop = 0.4,
            marginBottom = 0.4,
            marginLeft = 0.4,
            marginRight = 0.4
        };

        var result = await webView.CoreWebView2.CallDevToolsProtocolMethodAsync(
            "Page.printToPDF",
            JsonSerializer.Serialize(options)
        );

        var base64 = JsonDocument.Parse(result).RootElement.GetProperty("data").GetString();
        File.WriteAllBytes("output.pdf", Convert.FromBase64String(base64));
    }
}
// NuGet: Install-Package Microsoft.Web.WebView2.WinForms
using System;
using System.IO;
using System.Threading.Tasks;
using System.Text.Json;
using Microsoft.Web.WebView2.WinForms;
using Microsoft.Web.WebView2.Core;

class Program
{
    static async Task Main()
    {
        var webView = new WebView2();
        await webView.EnsureCoreWebView2Async();

        var htmlPath = Path.GetFullPath("document.html");
        var tcs = new TaskCompletionSource<bool>();
        webView.CoreWebView2.NavigationCompleted += (s, e) => tcs.SetResult(true);

        webView.CoreWebView2.Navigate($"file:///{htmlPath}");
        await tcs.Task;
        await Task.Delay(1000);

        var options = new
        {
            landscape = false,
            printBackground = true,
            paperWidth = 8.5,
            paperHeight = 11,
            marginTop = 0.4,
            marginBottom = 0.4,
            marginLeft = 0.4,
            marginRight = 0.4
        };

        var result = await webView.CoreWebView2.CallDevToolsProtocolMethodAsync(
            "Page.printToPDF",
            JsonSerializer.Serialize(options)
        );

        var base64 = JsonDocument.Parse(result).RootElement.GetProperty("data").GetString();
        File.WriteAllBytes("output.pdf", Convert.FromBase64String(base64));
    }
}
Imports System
Imports System.IO
Imports System.Threading.Tasks
Imports System.Text.Json
Imports Microsoft.Web.WebView2.WinForms
Imports Microsoft.Web.WebView2.Core

Module Program
    Async Function Main() As Task
        Dim webView As New WebView2()
        Await webView.EnsureCoreWebView2Async()

        Dim htmlPath As String = Path.GetFullPath("document.html")
        Dim tcs As New TaskCompletionSource(Of Boolean)()
        AddHandler webView.CoreWebView2.NavigationCompleted, Sub(s, e) tcs.SetResult(True)

        webView.CoreWebView2.Navigate($"file:///{htmlPath}")
        Await tcs.Task
        Await Task.Delay(1000)

        Dim options = New With {
            .landscape = False,
            .printBackground = True,
            .paperWidth = 8.5,
            .paperHeight = 11,
            .marginTop = 0.4,
            .marginBottom = 0.4,
            .marginLeft = 0.4,
            .marginRight = 0.4
        }

        Dim result As String = Await webView.CoreWebView2.CallDevToolsProtocolMethodAsync(
            "Page.printToPDF",
            JsonSerializer.Serialize(options)
        )

        Dim base64 As String = JsonDocument.Parse(result).RootElement.GetProperty("data").GetString()
        File.WriteAllBytes("output.pdf", Convert.FromBase64String(base64))
    End Function
End Module
$vbLabelText   $csharpLabel

IronPDF Approach:

// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.PaperSize = PdfPaperSize.Letter;
        renderer.RenderingOptions.MarginTop = 40;
        renderer.RenderingOptions.MarginBottom = 40;
        renderer.RenderingOptions.MarginLeft = 40;
        renderer.RenderingOptions.MarginRight = 40;
        renderer.RenderingOptions.PrintHtmlBackgrounds = true;

        var pdf = renderer.RenderHtmlFileAsPdf("document.html");
        pdf.SaveAs("output.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.PaperSize = PdfPaperSize.Letter;
        renderer.RenderingOptions.MarginTop = 40;
        renderer.RenderingOptions.MarginBottom = 40;
        renderer.RenderingOptions.MarginLeft = 40;
        renderer.RenderingOptions.MarginRight = 40;
        renderer.RenderingOptions.PrintHtmlBackgrounds = true;

        var pdf = renderer.RenderHtmlFileAsPdf("document.html");
        pdf.SaveAs("output.pdf");
    }
}
Imports IronPdf
Imports IronPdf.Rendering

Class Program
    Shared Sub Main()
        Dim renderer = New ChromePdfRenderer()
        renderer.RenderingOptions.PaperSize = PdfPaperSize.Letter
        renderer.RenderingOptions.MarginTop = 40
        renderer.RenderingOptions.MarginBottom = 40
        renderer.RenderingOptions.MarginLeft = 40
        renderer.RenderingOptions.MarginRight = 40
        renderer.RenderingOptions.PrintHtmlBackgrounds = True

        Dim pdf = renderer.RenderHtmlFileAsPdf("document.html")
        pdf.SaveAs("output.pdf")
    End Sub
End Class
$vbLabelText   $csharpLabel

WebView2 requires constructing anonymous objects, serializing to JSON, calling DevTools Protocol methods, parsing JSON responses, and manually decoding base64. IronPDF provides typed properties with clear names and enum values like PdfPaperSize.Letter.

WebView2 API to IronPDF Mapping Reference

This mapping accelerates migration by showing direct API equivalents:

WebView2 API IronPDF Equivalent
new WebView2() new ChromePdfRenderer()
EnsureCoreWebView2Async() N/A
NavigateToString(html) + PrintToPdfAsync() RenderHtmlAsPdf(html)
Navigate(url) + PrintToPdfAsync() RenderUrlAsPdf(url)
PrintSettings.PageWidth RenderingOptions.PaperSize
PrintSettings.PageHeight RenderingOptions.PaperSize
PrintSettings.MarginTop RenderingOptions.MarginTop
PrintSettings.Orientation RenderingOptions.PaperOrientation
ExecuteScriptAsync() JavaScript in HTML
AddScriptToExecuteOnDocumentCreatedAsync() HTML <script> tags
Navigation events WaitFor.JavaScript()
CallDevToolsProtocolMethodAsync("Page.printToPDF") RenderHtmlAsPdf()

Common Migration Issues and Solutions

Issue 1: Memory Leaks

WebView2 Problem: Memory is not fully released when disposing WebView2 instances. Long-running processes accumulate memory until crash.

IronPDF Solution: Proper garbage collection with no leaks:

// IronPDF - clean memory management
using (var pdf = renderer.RenderHtmlAsPdf(html))
{
    pdf.SaveAs("output.pdf");
} // Properly disposed
// IronPDF - clean memory management
using (var pdf = renderer.RenderHtmlAsPdf(html))
{
    pdf.SaveAs("output.pdf");
} // Properly disposed
Imports IronPdf

Using pdf = renderer.RenderHtmlAsPdf(html)
    pdf.SaveAs("output.pdf")
End Using
$vbLabelText   $csharpLabel

Issue 2: No UI Thread in Web Apps

WebView2 Problem: Requires STA thread with message pump. ASP.NET Core controllers cannot create WebView2 instances.

IronPDF Solution: Works on any thread:

// ASP.NET Core - just works
public async Task<IActionResult> GetPdf()
{
    var pdf = await renderer.RenderHtmlAsPdfAsync(html);
    return File(pdf.BinaryData, "application/pdf");
}
// ASP.NET Core - just works
public async Task<IActionResult> GetPdf()
{
    var pdf = await renderer.RenderHtmlAsPdfAsync(html);
    return File(pdf.BinaryData, "application/pdf");
}
Imports System.Threading.Tasks
Imports Microsoft.AspNetCore.Mvc

Public Class YourController
    Inherits Controller

    Public Async Function GetPdf() As Task(Of IActionResult)
        Dim pdf = Await renderer.RenderHtmlAsPdfAsync(html)
        Return File(pdf.BinaryData, "application/pdf")
    End Function
End Class
$vbLabelText   $csharpLabel

Issue 3: Navigation Event Complexity

WebView2 Problem: Must handle async navigation events, completion callbacks, and race conditions with TaskCompletionSource.

IronPDF Solution: Synchronous or async single method call:

// Simple and predictable
var pdf = renderer.RenderHtmlAsPdf(html);
// or
var pdf = await renderer.RenderHtmlAsPdfAsync(html);
// Simple and predictable
var pdf = renderer.RenderHtmlAsPdf(html);
// or
var pdf = await renderer.RenderHtmlAsPdfAsync(html);
$vbLabelText   $csharpLabel

Issue 4: Measurement Units

WebView2 uses inches for dimensions (8.5 x 11 for Letter). IronPDF uses millimeters for more precise measurements.

Conversion approach:

// WebView2: PageWidth = 8.27 (inches for A4)
// IronPDF: Use enum
renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;

// Or custom size in mm
renderer.RenderingOptions.SetCustomPaperSizeInMillimeters(210, 297);
// WebView2: PageWidth = 8.27 (inches for A4)
// IronPDF: Use enum
renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;

// Or custom size in mm
renderer.RenderingOptions.SetCustomPaperSizeInMillimeters(210, 297);
' WebView2: PageWidth = 8.27 (inches for A4)
' IronPDF: Use enum
renderer.RenderingOptions.PaperSize = PdfPaperSize.A4

' Or custom size in mm
renderer.RenderingOptions.SetCustomPaperSizeInMillimeters(210, 297)
$vbLabelText   $csharpLabel

WebView2 Migration Checklist

Pre-Migration Tasks

Document all WebView2 PDF generation code in your codebase. Identify where WebView2 is causing problems (memory leaks, crashes, deployment issues). Review the IronPDF documentation to familiarize with capabilities.

Code Update Tasks

  1. Remove Microsoft.Web.WebView2 NuGet package
  2. Install IronPdf NuGet package
  3. Remove WinForms/WPF dependencies if only used for PDF generation
  4. Replace WebView2 code with ChromePdfRenderer
  5. Remove STA thread requirements
  6. Remove navigation event handlers and TaskCompletionSource patterns
  7. Remove Task.Delay hacks
  8. Add IronPDF license initialization at startup

Post-Migration Testing

After migration, verify these aspects:

  • Test in target environment (ASP.NET, Docker, Linux if applicable)
  • Verify PDF output quality matches expectations
  • Test JavaScript-heavy pages render correctly
  • Verify headers and footers work with IronPDF's HTML capabilities
  • Load test for memory stability over extended operations
  • Test long-running scenarios without memory accumulation

Deployment Updates

  • Update Docker images if applicable (remove Edge WebView2 Runtime)
  • Remove Edge WebView2 Runtime dependency from server requirements
  • Update server requirements documentation
  • Verify cross-platform deployment works on target platforms

Key Benefits of Migrating to IronPDF

Moving from WebView2 to IronPDF provides several critical advantages:

Cross-Platform Support: Unlike WebView2's Windows-only limitation, IronPDF functions on Windows, Linux, macOS, and Docker. This flexibility enables deployment to Azure, AWS, GCP, and any cloud environment without platform constraints.

No UI Dependencies: IronPDF doesn't require STA threads, message pumps, or WinForms/WPF contexts. It works in console applications, web APIs, Windows Services, and background workers.

Memory Stability: Proper garbage collection eliminates the memory leaks that plague WebView2 in long-running processes. Production servers remain stable.

Simple API: Single method calls replace complex navigation events, completion callbacks, DevTools Protocol interactions, and base64 decoding.

Extended PDF Features: Headers, footers, watermarks, merge/split, digital signatures, password protection, and PDF/A compliance—features WebView2 cannot provide.

Active Development: As .NET 10 and C# 14 adoption increases through 2026, IronPDF's regular updates ensure compatibility with current and future .NET versions.

Curtis Chau
Curtis Chau
  Chat with engineering team now
Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...

Read More

Related Articles

30-day trial → Full product. No limits. No card. Start Free Trial

Iron Support Team

We're online 24 hours, 5 days a week.
Chat
Email
Call Me