Como migrar do MuPDF para o IronPDF em C#

Os Desafios do MuPDF

O MuPDF é um excelente renderizador de PDF, mas sua licença AGPL e foco exclusivo em renderização criam limitações significativas para desenvolvedores .NET que criam aplicativos comerciais:

1. Armadilha da Licença AGPL: O licenciamento viral do MuPDF exige que você disponibilize todo o código-fonte do seu aplicativo sob a licença AGPL ou compre licenças comerciais caras com preços opacos e que exigem contato com o departamento de vendas.

2. Foco exclusivo na renderização: O MuPDF é um visualizador/renderizador — não foi projetado para a criação de PDFs a partir de HTML, fluxos de trabalho de geração de documentos, preenchimento de formulários ou adição de marcas d'água e cabeçalhos/rodapés.

3. Sem suporte para HTML: O MuPDF não oferece suporte à conversão direta de HTML para PDF. Você precisaria usar outra biblioteca para converter o HTML para um formato compatível primeiro. Essa é uma limitação fundamental — o MuPDF é principalmente um visualizador/renderizador de PDF.

4. Dependências nativas: Binários específicos da plataforma exigem gerenciamento manual para Windows, Linux e macOS. As implementações do Docker tornam-se complexas devido aos requisitos de bibliotecas nativas, e o empacotamento da implementação apresenta desafios.

5. Manipulação limitada: Não há suporte integrado para mesclar/dividir PDFs, girar ou reordenar páginas, adicionar marcas d'água ou anotações, ou assinar assinaturas digitais.

6. Complexidade de interoperabilidade em C: as ligações nativas introduzem preocupações com o gerenciamento de memória, bugs específicos da plataforma e sobrecarga de serialização.

Comparação entre MuPDF e IronPDF

Para equipes que planejam a adoção do .NET 10 e do C# 14 até 2025 e 2026, o IronPDF oferece uma base preparada para o futuro como uma biblioteca .NET totalmente gerenciada, sem a complexidade da interoperabilidade nativa.

Esforço estimado por funcionalidade

Mudança de paradigma

A mudança fundamental nesta migração para o MuPDF é a transição de um visualizador apenas para renderização para uma solução completa de PDF:

MuPDF: MuPDFContext → MuPDFDocument → Iteração de página → Somente renderizar/extrair
IronPDF: PdfDocument.FromFile() → Manipulação completa → Criar/Editar/Mesclar/Proteger

Pré-requisitos

1. Ambiente .NET : .NET Framework 4.6.2+ ou .NET Core 3.1+ / .NET 5/6/7/8/9+
2. Acesso ao NuGet : Capacidade de instalar pacotes NuGet.
3. Licença do IronPDF : Obtenha sua chave de licença em IronPDF

Alterações no pacote NuGet

# Remove MuPDF packages
dotnet remove package MuPDF.NET
dotnet remove package MuPDFCore
dotnet remove package MuPDFCore.MuPDFWrapper

# Install IronPDF
dotnet add package IronPdf

# Remove MuPDF packages
dotnet remove package MuPDF.NET
dotnet remove package MuPDFCore
dotnet remove package MuPDFCore.MuPDFWrapper

# Install IronPDF
dotnet add package IronPdf

Remova também os binários nativos do MuPDF da sua instalação:

• Excluir mupdf.dll, libmupdf.so, libmupdf.dylib
• Remover pastas específicas da plataforma (runtimes/*/native/)
• Atualize os arquivos Docker para remover a instalação do MuPDF.

Configuração de licença

// Add at application startup (Program.cs or Startup.cs)
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

// Add at application startup (Program.cs or Startup.cs)
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

' Add at application startup (Program.vb or Startup.vb)
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"

Identificar o uso do MuPDF

# Find all MuPDF references
grep -r "MuPDF\|MuPDFCore\|MuPDFDocument" --include="*.cs" .

# Find all MuPDF references
grep -r "MuPDF\|MuPDFCore\|MuPDFDocument" --include="*.cs" .

Carregamento de documentos

Acesso à página

Extração de texto

Criação de PDF (Não disponível no MuPDF)

Manipulação de PDF (limitada em MuPDF)

Exemplo 1: Conversão de HTML para PDF (o MuPDF não consegue fazer isso)

Antes (MuPDF):

// NuGet: Install-Package MuPDF.NET
using MuPDFCore;
using System.IO;

class Program
{
    static void Main()
    {
        // MuPDF doesn't support HTML para PDF conversion directly
        // You would need to use another library to convert HTML to a supported format first
        // This is a limitation - MuPDF is primarily a PDF renderer/viewer

        // Alternative: Use a browser engine or intermediate conversion
        string html = "<html><body><h1>Hello World</h1></body></html>";

        // Not natively supported in MuPDF
        throw new NotSupportedException("MuPDF does not support direct HTML para PDF conversion");
    }
}

// NuGet: Install-Package MuPDF.NET
using MuPDFCore;
using System.IO;

class Program
{
    static void Main()
    {
        // MuPDF doesn't support HTML para PDF conversion directly
        // You would need to use another library to convert HTML to a supported format first
        // This is a limitation - MuPDF is primarily a PDF renderer/viewer

        // Alternative: Use a browser engine or intermediate conversion
        string html = "<html><body><h1>Hello World</h1></body></html>";

        // Not natively supported in MuPDF
        throw new NotSupportedException("MuPDF does not support direct HTML para PDF conversion");
    }
}

Imports MuPDFCore
Imports System.IO

Class Program
    Shared Sub Main()
        ' MuPDF doesn't support HTML to PDF conversion directly
        ' You would need to use another library to convert HTML to a supported format first
        ' This is a limitation - MuPDF is primarily a PDF renderer/viewer

        ' Alternative: Use a browser engine or intermediate conversion
        Dim html As String = "<html><body><h1>Hello World</h1></body></html>"

        ' Not natively supported in MuPDF
        Throw New NotSupportedException("MuPDF does not support direct HTML to PDF conversion")
    End Sub
End Class

Após (IronPDF):

// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        string html = "<html><body><h1>Hello World</h1></body></html>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("output.pdf");
    }
}

// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        string html = "<html><body><h1>Hello World</h1></body></html>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("output.pdf");
    }
}

Imports IronPdf

Class Program
    Shared Sub Main()
        Dim renderer = New ChromePdfRenderer()
        Dim html As String = "<html><body><h1>Hello World</h1></body></html>"

        Dim pdf = renderer.RenderHtmlAsPdf(html)
        pdf.SaveAs("output.pdf")
    End Sub
End Class

Este exemplo destaca a limitação mais significativa do MuPDF: ele não consegue converter HTML para PDF de forma alguma. O código MuPDF gera explicitamente o erro NotSupportedException porque a conversão de HTML para PDF simplesmente não é uma funcionalidade oferecida pelo MuPDF. Se você precisasse dessa funcionalidade com o MuPDF, teria que usar uma biblioteca separada como o wkhtmltopdf ou um mecanismo de navegador e, em seguida, carregar o PDF resultante com o MuPDF para visualização.

O IronPDF ChromePdfRenderer utiliza um mecanismo Chromium completo para renderizar HTML com suporte total a CSS3, JavaScript e padrões web modernos. O método RenderHtmlAsPdf() aceita strings HTML diretamente. Consulte a documentação de conversão de HTML para PDF para obter opções adicionais de renderização, incluindo renderização de URL e conversão de arquivos HTML.

Exemplo 2: Extração de Texto

Antes (MuPDF):

// NuGet: Install-Package MuPDF.NET
using MuPDFCore;
using System;
using System.Text;

class Program
{
    static void Main()
    {
        using (MuPDFDocument document = new MuPDFDocument("input.pdf"))
        {
            StringBuilder allText = new StringBuilder();

            for (int i = 0; i < document.Pages.Count; i++)
            {
                string pageText = document.Pages[i].GetText();
                allText.AppendLine(pageText);
            }

            Console.WriteLine(allText.ToString());
        }
    }
}

// NuGet: Install-Package MuPDF.NET
using MuPDFCore;
using System;
using System.Text;

class Program
{
    static void Main()
    {
        using (MuPDFDocument document = new MuPDFDocument("input.pdf"))
        {
            StringBuilder allText = new StringBuilder();

            for (int i = 0; i < document.Pages.Count; i++)
            {
                string pageText = document.Pages[i].GetText();
                allText.AppendLine(pageText);
            }

            Console.WriteLine(allText.ToString());
        }
    }
}

Imports MuPDFCore
Imports System
Imports System.Text

Class Program
    Shared Sub Main()
        Using document As New MuPDFDocument("input.pdf")
            Dim allText As New StringBuilder()

            For i As Integer = 0 To document.Pages.Count - 1
                Dim pageText As String = document.Pages(i).GetText()
                allText.AppendLine(pageText)
            Next

            Console.WriteLine(allText.ToString())
        End Using
    End Sub
End Class

Após (IronPDF):

// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var pdf = PdfDocument.FromFile("input.pdf");
        string text = pdf.ExtractAllText();

        Console.WriteLine(text);
    }
}

// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var pdf = PdfDocument.FromFile("input.pdf");
        string text = pdf.ExtractAllText();

        Console.WriteLine(text);
    }
}

Imports IronPdf
Imports System

Class Program
    Shared Sub Main()
        Dim pdf = PdfDocument.FromFile("input.pdf")
        Dim text As String = pdf.ExtractAllText()

        Console.WriteLine(text)
    End Sub
End Class

A abordagem MuPDF requer a criação de um bloco using com um MuPDFDocument, iteração manual através de document.Pages.Count com um loop for, chamando document.Pages[i].GetText() para cada página e construindo o texto com um StringBuilder. Este é um código de 12 linhas para uma extração de texto simples.

O IronPDF reduz isso a 3 linhas: carregar o documento com PdfDocument.FromFile(), chamar ExtractAllText() e imprimir o resultado. Sem iteração manual, sem StringBuilder, sem gerenciamento explícito de recursos com blocos using para esta operação simples. Saiba mais sobre extração de texto de PDFs .

Exemplo 3: Mesclar vários PDFs

Antes (MuPDF):

// NuGet: Install-Package MuPDF.NET
using MuPDFCore;
using System.IO;

class Program
{
    static void Main()
    {
        using (MuPDFDocument doc1 = new MuPDFDocument("file1.pdf"))
        using (MuPDFDocument doc2 = new MuPDFDocument("file2.pdf"))
        {
            // Create a new document
            using (MuPDFDocument mergedDoc = MuPDFDocument.Create())
            {
                // Copy pages from first document
                for (int i = 0; i < doc1.Pages.Count; i++)
                {
                    mergedDoc.CopyPage(doc1, i);
                }

                // Copy pages from second document
                for (int i = 0; i < doc2.Pages.Count; i++)
                {
                    mergedDoc.CopyPage(doc2, i);
                }

                mergedDoc.Save("merged.pdf");
            }
        }
    }
}

// NuGet: Install-Package MuPDF.NET
using MuPDFCore;
using System.IO;

class Program
{
    static void Main()
    {
        using (MuPDFDocument doc1 = new MuPDFDocument("file1.pdf"))
        using (MuPDFDocument doc2 = new MuPDFDocument("file2.pdf"))
        {
            // Create a new document
            using (MuPDFDocument mergedDoc = MuPDFDocument.Create())
            {
                // Copy pages from first document
                for (int i = 0; i < doc1.Pages.Count; i++)
                {
                    mergedDoc.CopyPage(doc1, i);
                }

                // Copy pages from second document
                for (int i = 0; i < doc2.Pages.Count; i++)
                {
                    mergedDoc.CopyPage(doc2, i);
                }

                mergedDoc.Save("merged.pdf");
            }
        }
    }
}

Imports MuPDFCore
Imports System.IO

Class Program
    Shared Sub Main()
        Using doc1 As New MuPDFDocument("file1.pdf"),
              doc2 As New MuPDFDocument("file2.pdf")

            ' Create a new document
            Using mergedDoc As MuPDFDocument = MuPDFDocument.Create()
                ' Copy pages from first document
                For i As Integer = 0 To doc1.Pages.Count - 1
                    mergedDoc.CopyPage(doc1, i)
                Next

                ' Copy pages from second document
                For i As Integer = 0 To doc2.Pages.Count - 1
                    mergedDoc.CopyPage(doc2, i)
                Next

                mergedDoc.Save("merged.pdf")
            End Using
        End Using
    End Sub
End Class

Após (IronPDF):

// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var pdf1 = PdfDocument.FromFile("file1.pdf");
        var pdf2 = PdfDocument.FromFile("file2.pdf");

        var merged = PdfDocument.Merge(pdf1, pdf2);
        merged.SaveAs("merged.pdf");
    }
}

// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var pdf1 = PdfDocument.FromFile("file1.pdf");
        var pdf2 = PdfDocument.FromFile("file2.pdf");

        var merged = PdfDocument.Merge(pdf1, pdf2);
        merged.SaveAs("merged.pdf");
    }
}

Imports IronPdf

Class Program
    Shared Sub Main()
        Dim pdf1 = PdfDocument.FromFile("file1.pdf")
        Dim pdf2 = PdfDocument.FromFile("file2.pdf")

        Dim merged = PdfDocument.Merge(pdf1, pdf2)
        merged.SaveAs("merged.pdf")
    End Sub
End Class

A operação de mesclagem MuPDF é particularmente verbosa. Você deve abrir ambos os documentos de origem em blocos aninhados using, criar um novo documento vazio com MuPDFDocument.Create(), iterar por cada página do primeiro documento chamando CopyPage(), iterar por cada página do segundo documento chamando CopyPage() e, finalmente, salvar. São mais de 20 linhas de código com aninhamento complexo.

O método estático PdfDocument.Merge() do IronPDF aceita vários documentos PDF e retorna um único documento mesclado. Toda a operação consiste em 4 linhas de código legível. Para mesclar vários documentos, você pode passar uma lista: PdfDocument.Merge(pdfList). Consulte a documentação sobre mesclagem e divisão de PDFs para obter opções adicionais.

Remover binários nativos

O MuPDF requer bibliotecas nativas específicas da plataforma. Após migrar para o IronPDF, remova todos os binários nativos do MuPDF:

# Delete native libraries
rm -f mupdf*.dll libmupdf*.so libmupdf*.dylib

# Remove runtime folders
rm -rf runtimes/*/native/

# Update Docker files to remove MuPDF installation

# Delete native libraries
rm -f mupdf*.dll libmupdf*.so libmupdf*.dylib

# Remove runtime folders
rm -rf runtimes/*/native/

# Update Docker files to remove MuPDF installation

O IronPDF é um código .NET totalmente gerenciado — sem binários nativos para gerenciar em diferentes plataformas.

Padrão de descarte simplificado

O MuPDF requer contexto explícito e gerenciamento de documentos:

// MuPDF: Nested using blocks required
using (MuPDFDocument document = new MuPDFDocument("input.pdf"))
{
    // Work with document
}

// IronPDF: Simpler pattern
var pdf = PdfDocument.FromFile("input.pdf");
// Work with pdf

// MuPDF: Nested using blocks required
using (MuPDFDocument document = new MuPDFDocument("input.pdf"))
{
    // Work with document
}

// IronPDF: Simpler pattern
var pdf = PdfDocument.FromFile("input.pdf");
// Work with pdf

Imports MuPDF

Using document As New MuPDFDocument("input.pdf")
    ' Work with document
End Using

Dim pdf = PdfDocument.FromFile("input.pdf")
' Work with pdf

Alteração do padrão de iteração da página

O MuPDF utiliza iteração baseada em índice com contagem de páginas explícita:

// MuPDF
for (int i = 0; i < document.Pages.Count; i++)
{
    var pageText = document.Pages[i].GetText();
}

// IronPDF (foreach supported)
foreach (var page in pdf.Pages)
{
    var pageText = page.Text;
}

// MuPDF
for (int i = 0; i < document.Pages.Count; i++)
{
    var pageText = document.Pages[i].GetText();
}

// IronPDF (foreach supported)
foreach (var page in pdf.Pages)
{
    var pageText = page.Text;
}

Imports System

' MuPDF
For i As Integer = 0 To document.Pages.Count - 1
    Dim pageText = document.Pages(i).GetText()
Next

' IronPDF (foreach supported)
For Each page In pdf.Pages
    Dim pageText = page.Text
Next

Novas funcionalidades disponíveis

Após migrar para o IronPDF, você obtém recursos que o MuPDF não oferece:

// Criação de PDF from HTML (not possible in MuPDF)
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello</h1>");

// Watermarks (not possible in MuPDF)
pdf.ApplyWatermark("<div style='color:red;opacity:0.3;'>DRAFT</div>");

// Password Protection (not possible in MuPDF)
pdf.SecuritySettings.OwnerPassword = "admin";
pdf.SecuritySettings.UserPassword = "user";

// Headers and Footers (not possible in MuPDF)
pdf.AddTextHeader("Document Title");
pdf.AddTextFooter("Page {page} of {total-pages}");

// Criação de PDF from HTML (not possible in MuPDF)
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello</h1>");

// Watermarks (not possible in MuPDF)
pdf.ApplyWatermark("<div style='color:red;opacity:0.3;'>DRAFT</div>");

// Password Protection (not possible in MuPDF)
pdf.SecuritySettings.OwnerPassword = "admin";
pdf.SecuritySettings.UserPassword = "user";

// Headers and Footers (not possible in MuPDF)
pdf.AddTextHeader("Document Title");
pdf.AddTextFooter("Page {page} of {total-pages}");

' Criação de PDF from HTML (not possible in MuPDF)
Dim pdf = renderer.RenderHtmlAsPdf("<h1>Hello</h1>")

' Watermarks (not possible in MuPDF)
pdf.ApplyWatermark("<div style='color:red;opacity:0.3;'>DRAFT</div>")

' Password Protection (not possible in MuPDF)
pdf.SecuritySettings.OwnerPassword = "admin"
pdf.SecuritySettings.UserPassword = "user"

' Headers and Footers (not possible in MuPDF)
pdf.AddTextHeader("Document Title")
pdf.AddTextFooter("Page {page} of {total-pages}")

Problema 1: Documento MuPDF não encontrado

Problema: a classe MuPDFDocument não existe no IronPDF.

Solução: Use PdfDocument.FromFile():

// MuPDF
using (MuPDFDocument document = new MuPDFDocument("input.pdf"))

// IronPDF
var pdf = PdfDocument.FromFile("input.pdf");

// MuPDF
using (MuPDFDocument document = new MuPDFDocument("input.pdf"))

// IronPDF
var pdf = PdfDocument.FromFile("input.pdf");

Imports MuPDF
Imports IronPDF

Using document As New MuPDFDocument("input.pdf")
End Using

Dim pdf = PdfDocument.FromFile("input.pdf")

Problema 2: Pages.Count não encontrado

Problema: o padrão document.Pages.Count não funciona.

Solução: Use pdf.PageCount:

// MuPDF
for (int i = 0; i < document.Pages.Count; i++)

// IronPDF
for (int i = 0; i < pdf.PageCount; i++)
// Or use: foreach (var page in pdf.Pages)

// MuPDF
for (int i = 0; i < document.Pages.Count; i++)

// IronPDF
for (int i = 0; i < pdf.PageCount; i++)
// Or use: foreach (var page in pdf.Pages)

' MuPDF
For i As Integer = 0 To document.Pages.Count - 1

' IronPDF
For i As Integer = 0 To pdf.PageCount - 1
' Or use: For Each page In pdf.Pages

Problema 3: GetText() não encontrado

Problema: o método page.GetText() não existe.

Solução: Use a propriedade page.Text ou pdf.ExtractAllText():

// MuPDF
string pageText = document.Pages[i].GetText();

// IronPDF
string pageText = pdf.Pages[i].Text;
// Or for all text:
string allText = pdf.ExtractAllText();

// MuPDF
string pageText = document.Pages[i].GetText();

// IronPDF
string pageText = pdf.Pages[i].Text;
// Or for all text:
string allText = pdf.ExtractAllText();

' MuPDF
Dim pageText As String = document.Pages(i).GetText()

' IronPDF
Dim pageText As String = pdf.Pages(i).Text
' Or for all text:
Dim allText As String = pdf.ExtractAllText()

Problema 4: CopyPage não encontrado

Problema: Padrão de cópia manual de páginas para mesclagem.

Solução: Use static PdfDocument.Merge():

// MuPDF
mergedDoc.CopyPage(doc1, i);

// IronPDF
var merged = PdfDocument.Merge(pdf1, pdf2);

// MuPDF
mergedDoc.CopyPage(doc1, i);

// IronPDF
var merged = PdfDocument.Merge(pdf1, pdf2);

' MuPDF
mergedDoc.CopyPage(doc1, i)

' IronPDF
Dim merged = PdfDocument.Merge(pdf1, pdf2)

Pré-migração

• Inventariar todos os usos do MuPDF na base de código
• Documentar todas as operações de renderização (DPI, fatores de escala)
• Identificar quaisquer necessidades de criação de PDFs (atualmente utilizando ferramentas externas)
• Listar os requisitos de extração de texto
• Analisar os scripts de implantação para o tratamento de binários nativos.
• Obtenha a chave de licença do IronPDF

Alterações no pacote

• Remover o pacote MuPDF.NET
• Remover o pacote MuPDFCore
• Remover o pacote MuPDFCore.MuPDFWrapper
• Instale o pacote NuGet IronPdf: dotnet add package IronPdf
• Atualizar importações de namespace

Alterações no código

• Adicionar configuração de chave de licença na inicialização
• Substitua MuPDFDocument por PdfDocument.FromFile()
• Substitua document.Pages.Count por pdf.PageCount Substitua page.GetText() por page.Text ou pdf.ExtractAllText()
• Substituir loops manuais CopyPage por PdfDocument.Merge()
• Remover blocos aninhados using para gerenciamento de contexto
• Adicione o código para criação de PDF, se necessário (HTML para PDF)

Pós-migração

• Remover binários nativos do MuPDF do projeto
• Atualize os arquivos Docker para remover a instalação do MuPDF.
• Remover pastas de tempo de execução específicas da plataforma
• Execute testes de regressão comparando a saída renderizada
• Testar em todas as plataformas alvo (Windows, Linux, macOS)
• Considere adicionar novas funcionalidades (marcas d'água, segurança, cabeçalhos/rodapés)