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 (Microsoft.Web.WebView2), offers developers a way to display web content within Windows applications. However, when development teams attempt to use WebView2 for PDF generation, they encounter architectural limitations that make it a poor fit for headless and server scenarios. WebView2 is a browser embedding control designed for UI applications, not a PDF generation library.

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

Why WebView2 Is a Poor Fit for PDF Generation

Before examining the migration path, it helps to understand why WebView2 is a poor fit for headless PDF creation:

Problem Impact Severity
Memory Leaks Memory growth reported in long-running processes that repeatedly create WebView2 instances. HIGH
Windows-Only No support for Linux, macOS, Docker, or non-Windows cloud environments CRITICAL
UI Thread Required Must run on an STA thread with a message pump. Not suitable for web servers or background APIs. CRITICAL
Not Designed for PDFs PrintToPdfAsync is a secondary capability, not a core feature HIGH
Unstable in Services Crashes and hangs reported in Windows Services and background workers HIGH
Complex Async Flow Navigation events, completion callbacks, race conditions HIGH
Edge Runtime Dependency Requires the Edge WebView2 Runtime installed on the target machine MEDIUM
No Headless Mode Designed around a UI control; not a headless renderer MEDIUM
Performance Slow startup, heavy resource consumption MEDIUM
No PDF Support Story Microsoft doesn't position WebView2 as a PDF generation product MEDIUM

Real-World Failure Scenarios

These code patterns commonly cause issues in production:

// WARNING: These patterns are known to cause problems in headless / server scenarios

// Problem 1: Memory growth - creates a new WebView2 per PDF
public async Task<byte[]> GeneratePdf(string html) // High call volume accumulates memory
{
    using var webView = new WebView2(); // Disposal does not fully reclaim native resources
    await webView.EnsureCoreWebView2Async();
    webView.CoreWebView2.NavigateToString(html);
    // ... memory growth reported over time
}

// 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
    }
}
// WARNING: These patterns are known to cause problems in headless / server scenarios

// Problem 1: Memory growth - creates a new WebView2 per PDF
public async Task<byte[]> GeneratePdf(string html) // High call volume accumulates memory
{
    using var webView = new WebView2(); // Disposal does not fully reclaim native resources
    await webView.EnsureCoreWebView2Async();
    webView.CoreWebView2.NavigateToString(html);
    // ... memory growth reported over time
}

// 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
    }
}
' WARNING: These patterns are known to cause problems in headless / server scenarios

' Problem 1: Memory growth - creates a new WebView2 per PDF
Public Async Function GeneratePdf(html As String) As Task(Of Byte()) ' High call volume accumulates memory
    Using webView As New WebView2() ' Disposal does not fully reclaim native resources
        Await webView.EnsureCoreWebView2Async()
        webView.CoreWebView2.NavigateToString(html)
        ' ... memory growth reported over time
    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
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 Memory growth reported 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
// (the WinForms host lives in the same package; no separate .WinForms package)
// Requires the Edge WebView2 Runtime installed on the target machine. Windows-only.
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);

        // PrintToPdfAsync(path, settings) returns Task<bool>; null = default settings
        bool ok = await webView.CoreWebView2.PrintToPdfAsync("output.pdf", null);
    }
}
// NuGet: Install-Package Microsoft.Web.WebView2
// (the WinForms host lives in the same package; no separate .WinForms package)
// Requires the Edge WebView2 Runtime installed on the target machine. Windows-only.
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);

        // PrintToPdfAsync(path, settings) returns Task<bool>; null = default settings
        bool ok = await webView.CoreWebView2.PrintToPdfAsync("output.pdf", null);
    }
}
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)

        ' PrintToPdfAsync(path, settings) returns Task(Of Boolean); Nothing = default settings
        Dim ok As Boolean = Await webView.CoreWebView2.PrintToPdfAsync("output.pdf", Nothing)
    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(), a Task.Delay(2000) to wait for rendering, and a final PrintToPdfAsync call that returns a Task<bool> indicating success. IronPDF eliminates this ceremony—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
// (Edge Chromium control; requires Edge WebView2 Runtime; Windows-only.)
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
// (Edge Chromium control; requires Edge WebView2 Runtime; Windows-only.)
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
// CreatePrintSettings() lives on CoreWebView2Environment.
// Margin* / PageWidth / PageHeight on CoreWebView2PrintSettings are in INCHES.
// PrintToPdfAsync(path, settings) returns Task<bool> (true on success) — not a stream.
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);

        CoreWebView2PrintSettings printSettings = webView.CoreWebView2.Environment.CreatePrintSettings();
        printSettings.Orientation = CoreWebView2PrintOrientation.Landscape;
        printSettings.MarginTop = 0.5;     // inches
        printSettings.MarginBottom = 0.5;  // inches
        printSettings.ShouldPrintBackgrounds = true;

        bool ok = await webView.CoreWebView2.PrintToPdfAsync("custom.pdf", printSettings);
        Console.WriteLine(ok ? "Custom PDF created" : "PrintToPdfAsync returned false");
    }
}
// NuGet: Install-Package Microsoft.Web.WebView2
// CreatePrintSettings() lives on CoreWebView2Environment.
// Margin* / PageWidth / PageHeight on CoreWebView2PrintSettings are in INCHES.
// PrintToPdfAsync(path, settings) returns Task<bool> (true on success) — not a stream.
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);

        CoreWebView2PrintSettings printSettings = webView.CoreWebView2.Environment.CreatePrintSettings();
        printSettings.Orientation = CoreWebView2PrintOrientation.Landscape;
        printSettings.MarginTop = 0.5;     // inches
        printSettings.MarginBottom = 0.5;  // inches
        printSettings.ShouldPrintBackgrounds = true;

        bool ok = await webView.CoreWebView2.PrintToPdfAsync("custom.pdf", printSettings);
        Console.WriteLine(ok ? "Custom PDF created" : "PrintToPdfAsync returned false");
    }
}
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 As CoreWebView2PrintSettings = webView.CoreWebView2.Environment.CreatePrintSettings()
        printSettings.Orientation = CoreWebView2PrintOrientation.Landscape
        printSettings.MarginTop = 0.5 ' inches
        printSettings.MarginBottom = 0.5 ' inches
        printSettings.ShouldPrintBackgrounds = True

        Dim ok As Boolean = Await webView.CoreWebView2.PrintToPdfAsync("custom.pdf", printSettings)
        Console.WriteLine(If(ok, "Custom PDF created", "PrintToPdfAsync returned false"))
    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 CoreWebView2.Environment, and an await on PrintToPdfAsync(path, settings) that returns Task<bool> rather than a stream. WebView2 expresses margins in inches; IronPDF uses millimeters via direct RenderingOptions properties.

Advanced PDF Options with DevTools Protocol

Complex WebView2 configurations require DevTools Protocol interaction.

WebView2 Approach:

// NuGet: Install-Package Microsoft.Web.WebView2
// Uses raw Chrome DevTools Protocol via CallDevToolsProtocolMethodAsync.
// (Page.printToPDF returns base64 in result.data; units are inches.)
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
// Uses raw Chrome DevTools Protocol via CallDevToolsProtocolMethodAsync.
// (Page.printToPDF returns base64 in result.data; units are inches.)
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 Growth

WebView2 Problem: Memory growth is reported in long-running processes that repeatedly create WebView2 instances, particularly without a steady message pump.

IronPDF Solution: Predictable disposal and using-friendly lifecycle:

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

Please noteWebView2 is a registered trademark of its respective owner. This site is not affiliated with, endorsed by, or sponsored by Microsoft. All product names, logos, and brands are property of their respective owners. Comparisons are for informational purposes only and reflect publicly available information at the time of writing.

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