Jak przeprowadzić migrację z Rotativa do IronPDF w języku C#

Zrozumienie Rotativa

Rotativa od dawna cieszy się popularnością wśród programistów jako narzędzie do generowania plików PDF w języku C#. Wykorzystuje narzędzie wkhtmltopdf do konwersji treści HTML na format PDF.Rotativato biblioteka open source zaprojektowana specjalnie dla aplikacji ASP.NET MVC. Jednak mimo żeRotativaprzyciągnęła znaczną grupę odbiorców, jej poleganie na przestarzałym stosie technologicznym stwarza wyzwania, które mogą nie być od razu oczywiste dla każdego programisty.

W swojej podstawie,Rotativazapewnia prosty sposób integracji generowania PDF w projektach ASP.NET MVC, wykorzystując wkhtmltopdf do funkcjonalności backendowych.

Krytyczne ostrzeżenie dotyczące bezpieczeństwa

Rotativa wykorzystuje bibliotekę wkhtmltopdf, która zawiera KRYTYCZNE, NIEZŁATANE LUKI W BEZPIECZEŃSTWIE.

Repozytorium GitHub wkhtmltopdf zostało zarchiwizowane (tylko do odczytu) 2 stycznia 2023. Strona statusu wnotki, że projekt zależy od Qt 4 (nie wspierany od 2015) i od gałęzi WebKit z 2012 roku, i wyraźnie ostrzega przed używaniem go z niepewnym HTML.CVE-2022-35583nie ma naprawionej wersji, więc każda aplikacja używającaRotativajest narażona, chyba że wejścia HTML są całkowicie zdezynfekowane na wstępie.

1. Środowisko .NET: .NET Framework 4.6.2+ lub .NET Core 3.1+ / .NET 5/6/7/8/9+
2. Dostęp do NuGet: Możliwość instalowania pakietów NuGet
3. Licencja IronPDF: Uzyskaj klucz licencyjny na stronie ironpdf.com

Zmiany w pakiecie NuGet

Oryginalny pakiet Rotativa jest przeznaczony dla klasycznego ASP.NET MVC 5 (ostatnia wersja v1.7.3, 2017-09-29). Fork społecznościowy Rotativa.AspNetCore (webgio) osiągnął v1.4.0 w dniu 2024-11-06 i wspiera od .NET Core 3.1 do .NET 8 — ale oba pakiety nadal dostarczają binarium wkhtmltopdf 0.12.6 (ostatnia wersja upstream czerwiec 2020).

# Remove Rotativa
dotnet remove package Rotativa
dotnet remove package Rotativa.AspNetCore

# Install IronPDF
dotnet add package IronPdf

# Remove Rotativa
dotnet remove package Rotativa
dotnet remove package Rotativa.AspNetCore

# Install IronPDF
dotnet add package IronPdf

Usuń pliki binarne wkhtmltopdf

Usuń te pliki z projektu:

• wkhtmltopdf.exe
• wkhtmltox.dll
• Jakiekolwiek foldery Rotativa/

Są to źródła CVE-2022-35583.IronPDF nie wymaga natywnych plików binarnych.

Konfiguracja licencji

// Add in Program.cs or Startup.cs
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

// Add in Program.cs or Startup.cs
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

' Add in Program.vb or Startup.vb
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"

Zmiany w przestrzeni nazw

// Before: Rotativa
using Rotativa;
using Rotativa.Options;
using Rotativa.AspNetCore;

// After: IronPDF
using IronPdf;
using IronPdf.Rendering;

// Before: Rotativa
using Rotativa;
using Rotativa.Options;
using Rotativa.AspNetCore;

// After: IronPDF
using IronPdf;
using IronPdf.Rendering;

' Before: Rotativa
Imports Rotativa
Imports Rotativa.Options
Imports Rotativa.AspNetCore

' After: IronPDF
Imports IronPdf
Imports IronPdf.Rendering

Mapowania klas podstawowych

Konwersja symboli zastępczych stron

Przykład 1: Konwersja HTML do PDF

Przed (Rotativa):

// NuGet: Install-Package Rotativa.AspNetCore
using Microsoft.AspNetCore.Mvc;
using Rotativa.AspNetCore;
using System.Threading.Tasks;

namespace RotativaExample
{
    public class PdfController : Controller
    {
        public async Task<IActionResult> GeneratePdf()
        {
            var htmlContent = "<h1>Hello World</h1><p>This is a PDF document.</p>";

            //Rotativarequires returning a ViewAsPdf result from MVC controller
            return new ViewAsPdf()
            {
                ViewName = "PdfView",
                PageSize = Rotativa.AspNetCore.Options.Size.A4
            };
        }
    }
}

// NuGet: Install-Package Rotativa.AspNetCore
using Microsoft.AspNetCore.Mvc;
using Rotativa.AspNetCore;
using System.Threading.Tasks;

namespace RotativaExample
{
    public class PdfController : Controller
    {
        public async Task<IActionResult> GeneratePdf()
        {
            var htmlContent = "<h1>Hello World</h1><p>This is a PDF document.</p>";

            //Rotativarequires returning a ViewAsPdf result from MVC controller
            return new ViewAsPdf()
            {
                ViewName = "PdfView",
                PageSize = Rotativa.AspNetCore.Options.Size.A4
            };
        }
    }
}

Imports Microsoft.AspNetCore.Mvc
Imports Rotativa.AspNetCore
Imports System.Threading.Tasks

Namespace RotativaExample
    Public Class PdfController
        Inherits Controller

        Public Async Function GeneratePdf() As Task(Of IActionResult)
            Dim htmlContent As String = "<h1>Hello World</h1><p>This is a PDF document.</p>"

            ' Rotativa requires returning a ViewAsPdf result from MVC controller
            Return New ViewAsPdf() With {
                .ViewName = "PdfView",
                .PageSize = Rotativa.AspNetCore.Options.Size.A4
            }
        End Function
    End Class
End Namespace

Po (IronPDF):

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

namespace IronPdfExample
{
    class Program
    {
        static void Main(string[] args)
        {
            var renderer = new ChromePdfRenderer();
            var htmlContent = "<h1>Hello World</h1><p>This is a PDF document.</p>";

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

            Console.WriteLine("PDF generated successfully!");
        }
    }
}

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

namespace IronPdfExample
{
    class Program
    {
        static void Main(string[] args)
        {
            var renderer = new ChromePdfRenderer();
            var htmlContent = "<h1>Hello World</h1><p>This is a PDF document.</p>";

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

            Console.WriteLine("PDF generated successfully!");
        }
    }
}

Imports IronPdf
Imports System

Namespace IronPdfExample
    Class Program
        Shared Sub Main(ByVal args As String())
            Dim renderer = New ChromePdfRenderer()
            Dim htmlContent = "<h1>Hello World</h1><p>This is a PDF document.</p>"

            Dim pdf = renderer.RenderHtmlAsPdf(htmlContent)
            pdf.SaveAs("output.pdf")

            Console.WriteLine("PDF generated successfully!")
        End Sub
    End Class
End Namespace

Ten przykład ilustruje podstawową różnicę architektoniczną.Rotativawymaga zwrócenia wyniku ViewAsPdf z akcji kontrolera MVC, co wiąże cię do frameworku ASP.NET MVC. Ten wzorzec działa wyłącznie w ramach potoku żądań MVC i wymaga widoku Razor do renderowania.

IronPDF działa wszędzie: w aplikacjach konsolowych, interfejsach API sieci Web, Blazor, Razor Pages lub dowolnym typie projektu .NET. Wywołujesz RenderHtmlAsPdf() z ciągiem HTML i zapisujesz rezultat. Nie jest wymagany kontroler MVC, brak zależności od widoku. Kompleksowe przykłady można znaleźć w dokumentacji dotyczącej konwersji HTML do PDF.

Przykład 2: Konwersja adresów URL do formatu PDF

Przed (Rotativa):

// NuGet: Install-Package Rotativa.AspNetCore
using Microsoft.AspNetCore.Mvc;
using Rotativa.AspNetCore;
using System.Threading.Tasks;

namespace RotativaExample
{
    public class UrlPdfController : Controller
    {
        public async Task<IActionResult> ConvertUrlToPdf()
        {
            //Rotativaworks within MVC framework and returns ActionResult
            return new UrlAsPdf("https://www.example.com")
            {
                FileName = "webpage.pdf",
                PageSize = Rotativa.AspNetCore.Options.Size.A4,
                PageOrientation = Rotativa.AspNetCore.Options.Orientation.Portrait
            };
        }
    }
}

// NuGet: Install-Package Rotativa.AspNetCore
using Microsoft.AspNetCore.Mvc;
using Rotativa.AspNetCore;
using System.Threading.Tasks;

namespace RotativaExample
{
    public class UrlPdfController : Controller
    {
        public async Task<IActionResult> ConvertUrlToPdf()
        {
            //Rotativaworks within MVC framework and returns ActionResult
            return new UrlAsPdf("https://www.example.com")
            {
                FileName = "webpage.pdf",
                PageSize = Rotativa.AspNetCore.Options.Size.A4,
                PageOrientation = Rotativa.AspNetCore.Options.Orientation.Portrait
            };
        }
    }
}

Imports Microsoft.AspNetCore.Mvc
Imports Rotativa.AspNetCore
Imports System.Threading.Tasks

Namespace RotativaExample
    Public Class UrlPdfController
        Inherits Controller

        Public Async Function ConvertUrlToPdf() As Task(Of IActionResult)
            ' Rotativa works within MVC framework and returns ActionResult
            Return New UrlAsPdf("https://www.example.com") With {
                .FileName = "webpage.pdf",
                .PageSize = Rotativa.AspNetCore.Options.Size.A4,
                .PageOrientation = Rotativa.AspNetCore.Options.Orientation.Portrait
            }
        End Function
    End Class
End Namespace

Po (IronPDF):

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

namespace IronPdfExample
{
    class Program
    {
        static void Main(string[] args)
        {
            var renderer = new ChromePdfRenderer();

            var pdf = renderer.RenderUrlAsPdf("https://www.example.com");
            pdf.SaveAs("webpage.pdf");

            Console.WriteLine("URL converted to PDF successfully!");
        }
    }
}

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

namespace IronPdfExample
{
    class Program
    {
        static void Main(string[] args)
        {
            var renderer = new ChromePdfRenderer();

            var pdf = renderer.RenderUrlAsPdf("https://www.example.com");
            pdf.SaveAs("webpage.pdf");

            Console.WriteLine("URL converted to PDF successfully!");
        }
    }
}

Imports IronPdf
Imports System

Namespace IronPdfExample
    Class Program
        Shared Sub Main(ByVal args As String())
            Dim renderer = New ChromePdfRenderer()

            Dim pdf = renderer.RenderUrlAsPdf("https://www.example.com")
            pdf.SaveAs("webpage.pdf")

            Console.WriteLine("URL converted to PDF successfully!")
        End Sub
    End Class
End Namespace

Klasa UrlAsPdfRotativawymaga zwrócenia ActionResult z kontrolera MVC. Metoda RenderUrlAsPdf()IronPDF może być wywołana z dowolnego kontekstu i zwraca obiekt PdfDocument bezpośrednio. Renderowanie adresów URL wykorzystuje nowoczesny silnik Chromium zamiast podatnego na ataki i przestarzałego silnika WebKit używanego przez wkhtmltopdf. Dowiedz się więcej z naszych samouczków.

Przykład 3: Nagłówki i stopki z numerami stron

Przed (Rotativa):

// NuGet: Install-Package Rotativa.AspNetCore
using Microsoft.AspNetCore.Mvc;
using Rotativa.AspNetCore;
using Rotativa.AspNetCore.Options;
using System.Threading.Tasks;

namespace RotativaExample
{
    public class HeaderFooterController : Controller
    {
        public async Task<IActionResult> GeneratePdfWithHeaderFooter()
        {
            return new ViewAsPdf("Report")
            {
                PageSize = Size.A4,
                // Margins(top, right, bottom, left)
                PageMargins = new Margins(20, 10, 20, 10),
                CustomSwitches = "--header-center \"Page Header\" --footer-center \"Page [page] of [topage]\""
            };
        }
    }
}

// NuGet: Install-Package Rotativa.AspNetCore
using Microsoft.AspNetCore.Mvc;
using Rotativa.AspNetCore;
using Rotativa.AspNetCore.Options;
using System.Threading.Tasks;

namespace RotativaExample
{
    public class HeaderFooterController : Controller
    {
        public async Task<IActionResult> GeneratePdfWithHeaderFooter()
        {
            return new ViewAsPdf("Report")
            {
                PageSize = Size.A4,
                // Margins(top, right, bottom, left)
                PageMargins = new Margins(20, 10, 20, 10),
                CustomSwitches = "--header-center \"Page Header\" --footer-center \"Page [page] of [topage]\""
            };
        }
    }
}

Imports Microsoft.AspNetCore.Mvc
Imports Rotativa.AspNetCore
Imports Rotativa.AspNetCore.Options
Imports System.Threading.Tasks

Namespace RotativaExample
    Public Class HeaderFooterController
        Inherits Controller

        Public Async Function GeneratePdfWithHeaderFooter() As Task(Of IActionResult)
            Return New ViewAsPdf("Report") With {
                .PageSize = Size.A4,
                ' Margins(top, right, bottom, left)
                .PageMargins = New Margins(20, 10, 20, 10),
                .CustomSwitches = "--header-center ""Page Header"" --footer-center ""Page [page] of [topage]"""
            }
        End Function
    End Class
End Namespace

Po (IronPDF):

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

namespace IronPdfExample
{
    class Program
    {
        static void Main(string[] args)
        {
            var renderer = new ChromePdfRenderer();

            renderer.RenderingOptions.TextHeader = new TextHeaderFooter()
            {
                CenterText = "Page Header",
                DrawDividerLine = true
            };

            renderer.RenderingOptions.TextFooter = new TextHeaderFooter()
            {
                CenterText = "Page {page} of {total-pages}",
                DrawDividerLine = true
            };

            var htmlContent = "<h1>Report Title</h1><p>Report content goes here.</p>";
            var pdf = renderer.RenderHtmlAsPdf(htmlContent);
            pdf.SaveAs("report.pdf");

            Console.WriteLine("PDF with headers and footers created successfully!");
        }
    }
}

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

namespace IronPdfExample
{
    class Program
    {
        static void Main(string[] args)
        {
            var renderer = new ChromePdfRenderer();

            renderer.RenderingOptions.TextHeader = new TextHeaderFooter()
            {
                CenterText = "Page Header",
                DrawDividerLine = true
            };

            renderer.RenderingOptions.TextFooter = new TextHeaderFooter()
            {
                CenterText = "Page {page} of {total-pages}",
                DrawDividerLine = true
            };

            var htmlContent = "<h1>Report Title</h1><p>Report content goes here.</p>";
            var pdf = renderer.RenderHtmlAsPdf(htmlContent);
            pdf.SaveAs("report.pdf");

            Console.WriteLine("PDF with headers and footers created successfully!");
        }
    }
}

Imports IronPdf
Imports IronPdf.Rendering
Imports System

Namespace IronPdfExample
    Class Program
        Shared Sub Main(ByVal args As String())
            Dim renderer = New ChromePdfRenderer()

            renderer.RenderingOptions.TextHeader = New TextHeaderFooter() With {
                .CenterText = "Page Header",
                .DrawDividerLine = True
            }

            renderer.RenderingOptions.TextFooter = New TextHeaderFooter() With {
                .CenterText = "Page {page} of {total-pages}",
                .DrawDividerLine = True
            }

            Dim htmlContent = "<h1>Report Title</h1><p>Report content goes here.</p>"
            Dim pdf = renderer.RenderHtmlAsPdf(htmlContent)
            pdf.SaveAs("report.pdf")

            Console.WriteLine("PDF with headers and footers created successfully!")
        End Sub
    End Class
End Namespace

Rotativa używa CustomSwitches do przekazywania argumentów wiersza poleceń do wkhtmltopdf, w tym konfiguracji nagłówka i stopki z takimi placeholderami jak [page] i [topage]. To podejście oparte na ciągach znaków jest podatne na błędy i trudne do zweryfikowania w czasie kompilacji.

IronPDF używa silnie typowanych obiektów TextHeaderFooter z właściwościami takimi jak CenterText i DrawDividerLine. Składnia placeholderów zmienia się z [page] na {page} i z [topage] na {total-pages}. Właściwości typowane zapewniają funkcję IntelliSense, sprawdzanie w czasie kompilacji oraz brak ryzyka wystąpienia literówek.

Łączenie plików PDF

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

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

Dim merged = PdfDocument.Merge(pdf1, pdf2, pdf3)
merged.SaveAs("complete.pdf")

Podpisy cyfrowe

var signature = new PdfSignature("certificate.pfx", "password");
pdf.Sign(signature);

var signature = new PdfSignature("certificate.pfx", "password");
pdf.Sign(signature);

Dim signature = New PdfSignature("certificate.pfx", "password")
pdf.Sign(signature)

Ochrona hasłem

pdf.SecuritySettings.UserPassword = "secret";

pdf.SecuritySettings.UserPassword = "secret";

pdf.SecuritySettings.UserPassword = "secret"

Znaki wodne

pdf.ApplyWatermark("<h1 style='color:red; opacity:0.3;'>DRAFT</h1>");

pdf.ApplyWatermark("<h1 style='color:red; opacity:0.3;'>DRAFT</h1>");

IRON VB CONVERTER ERROR developers@ironsoftware.com

Zgodność z normą archiwizacji PDF/A

pdf.SaveAsPdfA("archive.pdf", PdfAVersions.PdfA3b);

pdf.SaveAsPdfA("archive.pdf", PdfAVersions.PdfA3b);

pdf.SaveAsPdfA("archive.pdf", PdfAVersions.PdfA3b)

Obsługa nowoczesnego CSS

// This now works (broke in Rotativa)
var html = @"
    <div style='display: flex; justify-content: space-between;'>
        <div>Left</div>
        <div>Right</div>
    </div>
    <div style='display: grid; grid-template-columns: 1fr 1fr 1fr;'>
        <div>Col 1</div><div>Col 2</div><div>Col 3</div>
    </div>";
var pdf = renderer.RenderHtmlAsPdf(html);  // Works!

// This now works (broke in Rotativa)
var html = @"
    <div style='display: flex; justify-content: space-between;'>
        <div>Left</div>
        <div>Right</div>
    </div>
    <div style='display: grid; grid-template-columns: 1fr 1fr 1fr;'>
        <div>Col 1</div><div>Col 2</div><div>Col 3</div>
    </div>";
var pdf = renderer.RenderHtmlAsPdf(html);  // Works!

' This now works (broke in Rotativa)
Dim html As String = "
    <div style='display: flex; justify-content: space-between;'>
        <div>Left</div>
        <div>Right</div>
    </div>
    <div style='display: grid; grid-template-columns: 1fr 1fr 1fr;'>
        <div>Col 1</div><div>Col 2</div><div>Col 3</div>
    </div>"
Dim pdf = renderer.RenderHtmlAsPdf(html)  ' Works!

Przed migracją

• Zidentyfikuj wszystkie wystąpieniaRotativaw kodzie źródłowym
• Dokument CustomSwitches używany do konwersji do RenderingOptions
• Zwróć uwagę na składnię placeholderów nagłówków/ścieżki do konwersji ([page] → {page})
• Uzyskaj klucz licencyjny IronPDF ze strony ironpdf.com

Zmiany w pakiecie

• Usuń pakiety NuGet Rotativa i Rotativa.AspNetCore
• Usuń binaria wkhtmltopdf (wkhtmltopdf.exe, wkhtmltox.dll)
• Zainstaluj pakiet NuGet IronPdf

Zmiany w kodzie

• Zaktualizuj importy przestrzeni nazw (using Rotativa; → using IronPdf;)
• Zamień ViewAsPdf na ChromePdfRenderer + RenderHtmlAsPdf()
• Zamień UrlAsPdf na RenderUrlAsPdf()
• Przekształć CustomSwitches na właściwości RenderingOptions
• Zaktualizuj składnię placeholderów ([page] → {page}, [topage] → {total-pages})
• Zamień PageMargins na indywidualne MarginRight
• W odpowiednich miejscach należy przejść na wzorzec asynchroniczny
• Dodaj inicjalizację licencji podczas uruchamiania aplikacji

Po migracji

• Sprawdź, czy generowanie plików PDF działa poprawnie
• Porównaj jakość wydruku PDF (Chromium renderuje dokładniej)
• Sprawdź ulepszenia w renderowaniu CSS (Flexbox/Grid teraz działają)
• Testowanie wykonywania kodu JavaScript (obecnie działa niezawodnie w przeglądarce Chromium)
• Sprawdź, czy skanowanie bezpieczeństwa zakończyło się pomyślnie (brak flag CVE-2022-35583)
• Zaktualizuj konfiguracje Docker, aby usunąć instalację wkhtmltopdf