How to Convert Razor Views to PDFs Headlessly in C#

Updated: 2026年6月4日

在C#中将Razor视图转换为PDF，通过使用RenderHtmlAsPdf方法来生成PDF文档，无需GUI或浏览器窗口。

无头渲染无需图形用户界面即可处理网页内容。虽然IronPdf.Extensions.Razor很有用，但它缺乏无头渲染功能。本指南弥补了这一不足。

我们将使用cshtml转换为HTML，然后使用IronPDF生成PDF。

快速入门：秒速将Razor视图转换为 PDF

using IronPDF 的无头转换功能将 Razor 视图转换为 PDF。使用IronPdf.HtmlToPdf.StaticRender.RenderHtmlAsPdf将Razor视图中的HTML渲染为PDF。这种方法可在 ASP.NET Core 环境中无缝运行。

1Install IronPDF with NuGet Package Manager
PM > Install-Package IronPdf
```
Install-Package IronPdf
```

2复制并运行这段代码。

var html = await RazorTemplateEngine.RenderAsync("Views/Template.cshtml", model); 
new IronPdf.ChromePdfRenderer().RenderHtmlAsPdf(html).SaveAs("output.pdf");

var html = await RazorTemplateEngine.RenderAsync("Views/Template.cshtml", model); 
new IronPdf.ChromePdfRenderer().RenderHtmlAsPdf(html).SaveAs("output.pdf");

3部署到您的生产环境中进行测试

通过免费试用立即在您的项目中开始使用IronPDF

最小工作流程（5 个步骤）

下载用于在 ASP.NET Core Web App 中将 Razor 视图转换为 PDF 的 C# 库。
创建一个新的Razor视图并编辑文件以显示数据
使用 RenderAsync 方法将 Razor View 转换为 HTML
使用 RenderHtmlAsPdf 方法将 HTML 转换为 PDF
下载样本项目以快速开始

安装Razor.Templating.Core以在ASP.NET Core Web应用程序中将Razor视图转换为HTML。

# Install the Razor.Templating.Core package using NuGet Package Manager
Install-Package Razor.Templating.Core

# Install the Razor.Templating.Core package using NuGet Package Manager
Install-Package Razor.Templating.Core

SHELL

如何设置我的 ASP.NET Core 项目进行 Razor 到 PDF 的转换？

您需要一个 ASP.NET Core Web App（模型-视图-控制器）项目来将视图转换为 PDF。设置包括在 Visual Studio 中创建项目、安装 NuGet 软件包和配置项目结构。有关类似技术，请参阅在 MVC Core 中将 CSHTML 转换为 PDF 或使用 Razor Pages 将 CSHTML 转换为 PDF 。

为什么我需要Razor.Templating.Core而不是`IronPdf.Extensions.Razor`？

Razor.Templating.Core提供真正的无头渲染——无需Web上下文或浏览器窗口即可将Razor视图转换为HTML。这适合后台服务、控制台应用程序或无用户界面环境。 IronPdf.Extensions.Razor需要Web上下文才能运行。

什么项目类型最适合无头生成 PDF？

ASP.NET Core Web App（模型-视图-控制器）项目提供了必要的 Razor View 基础设施，具有灵活的部署选项。在后台服务、Azure Functions或控制台应用程序中使用这种方法。请参阅将 IronPDF 部署到 Azure 以实现基于云的生成。

如何安装所需的 NuGet 软件包？

using NuGet 软件包管理器安装软件包。您需要Razor.Templating.Core：

// Install via Package Manager Console
Install-Package IronPdf
Install-Package Razor.Templating.Core

// Or add to your .csproj file
// <PackageReference Include="IronPdf" Version="2024.x.x" />
// <PackageReference Include="Razor.Templating.Core" Version="1.x.x" />

// Install via Package Manager Console
Install-Package IronPdf
Install-Package Razor.Templating.Core

// Or add to your .csproj file
// <PackageReference Include="IronPdf" Version="2024.x.x" />
// <PackageReference Include="Razor.Templating.Core" Version="1.x.x" />

SHELL

如何创建和配置用于生成 PDF 的 Razor 视图？

右键单击 "Home "文件夹。选择 "添加"，然后选择 "添加视图"。
创建一个名为 "Data.cshtml "的空 Razor 视图。

Visual Studio解决方案资源管理器上下文菜单显示添加>视图选项以创建新的MVC视图

我应该在 Razor 视图中添加哪些 HTML 内容？

添加要渲染为 PDF 的 HTML：

<table class="table">
    <tr>
        <th>Name</th>
        <th>Title</th>
        <th>Description</th>
    </tr>
    <tr>
        <td>John Doe</td>
        <td>Software Engineer</td>
        <td>Experienced software engineer specializing in web development.</td>
    </tr>
    <tr>
        <td>Alice Smith</td>
        <td>Project Manager</td>
        <td>Seasoned project manager with expertise in agile methodologies.</td>
    </tr>
    <tr>
        <td>Michael Johnson</td>
        <td>Data Analyst</td>
        <td>Skilled data analyst proficient in statistical analysis and data visualization.</td>
    </tr>
</table>

<table class="table">
    <tr>
        <th>Name</th>
        <th>Title</th>
        <th>Description</th>
    </tr>
    <tr>
        <td>John Doe</td>
        <td>Software Engineer</td>
        <td>Experienced software engineer specializing in web development.</td>
    </tr>
    <tr>
        <td>Alice Smith</td>
        <td>Project Manager</td>
        <td>Seasoned project manager with expertise in agile methodologies.</td>
    </tr>
    <tr>
        <td>Michael Johnson</td>
        <td>Data Analyst</td>
        <td>Skilled data analyst proficient in statistical analysis and data visualization.</td>
    </tr>
</table>

HTML

对于复杂的布局，请使用 CSS 和打印样式，以确保完美的 PDF 渲染。 IronPDF 支持现代 CSS3 功能，可实现复杂的文档布局。

为什么使用表格显示 PDF 数据？

表格提供了结构化、有条理的信息，可以很好地翻译成印刷文件。译文必须保持跨平台的格式一致，并能以 PDF 格式阅读。 IronPDF 的渲染引擎可以很好地处理表格布局，保留边框、间距和对齐方式。对于高级格式，请探索自定义页边距以优化布局。

PDF 输出的常见样式考虑因素有哪些？

对于 PDF 输出，请使用特定于印刷的 CSS 媒体查询、固定像素值而不是相对单位，并使用嵌入式字体以获得一致的渲染效果。 IronPDF 支持 web 字体和图标字体，以实现品牌一致性。考虑多页文档的分页符和适当的页边距，以达到专业的外观效果。

如何配置`Program.cs`以进行无头PDF渲染？

在Program.cs中，添加此代码。它使用RenderHtmlAsPdf。使用RenderingOptions实现自定义文本、页眉、页脚、边距和页码。

app.MapGet("/PrintPdf", async () =>
{
    // Set your IronPDF license key
    IronPdf.License.LicenseKey = "IRONPDF-MYLICENSE-KEY-1EF01";
    
    // Enable detailed logging for troubleshooting
    IronPdf.Logging.Logger.LoggingMode = IronPdf.Logging.Logger.LoggingModes.All;

    // Render the Razor view to an HTML string
    string html = await RazorTemplateEngine.RenderAsync("Views/Home/Data.cshtml");

    // Create a new instance of ChromePdfRenderer 
    ChromePdfRenderer renderer = new ChromePdfRenderer();
    
    // Configure rendering options for professional output
    renderer.RenderingOptions.PaperSize = IronPdf.PdfPaperSize.A4;
    renderer.RenderingOptions.MarginTop = 25;
    renderer.RenderingOptions.MarginBottom = 25;
    renderer.RenderingOptions.MarginLeft = 20;
    renderer.RenderingOptions.MarginRight = 20;
   
    // Render the HTML string as a PDF document
    PdfDocument pdf = renderer.RenderHtmlAsPdf(html, "./wwwroot");

    // Return the PDF file as a response
    return Results.File(pdf.BinaryData, "application/pdf", "razorViewToPdf.pdf");
});

app.MapGet("/PrintPdf", async () =>
{
    // Set your IronPDF license key
    IronPdf.License.LicenseKey = "IRONPDF-MYLICENSE-KEY-1EF01";
    
    // Enable detailed logging for troubleshooting
    IronPdf.Logging.Logger.LoggingMode = IronPdf.Logging.Logger.LoggingModes.All;

    // Render the Razor view to an HTML string
    string html = await RazorTemplateEngine.RenderAsync("Views/Home/Data.cshtml");

    // Create a new instance of ChromePdfRenderer 
    ChromePdfRenderer renderer = new ChromePdfRenderer();
    
    // Configure rendering options for professional output
    renderer.RenderingOptions.PaperSize = IronPdf.PdfPaperSize.A4;
    renderer.RenderingOptions.MarginTop = 25;
    renderer.RenderingOptions.MarginBottom = 25;
    renderer.RenderingOptions.MarginLeft = 20;
    renderer.RenderingOptions.MarginRight = 20;
   
    // Render the HTML string as a PDF document
    PdfDocument pdf = renderer.RenderHtmlAsPdf(html, "./wwwroot");

    // Return the PDF file as a response
    return Results.File(pdf.BinaryData, "application/pdf", "razorViewToPdf.pdf");
});

Imports IronPdf
Imports Microsoft.AspNetCore.Http

app.MapGet("/PrintPdf", Async Function() As Task(Of IResult)
    ' Set your IronPDF license key
    IronPdf.License.LicenseKey = "IRONPDF-MYLICENSE-KEY-1EF01"
    
    ' Enable detailed logging for troubleshooting
    IronPdf.Logging.Logger.LoggingMode = IronPdf.Logging.Logger.LoggingModes.All

    ' Render the Razor view to an HTML string
    Dim html As String = Await RazorTemplateEngine.RenderAsync("Views/Home/Data.cshtml")

    ' Create a new instance of ChromePdfRenderer 
    Dim renderer As New ChromePdfRenderer()
    
    ' Configure rendering options for professional output
    renderer.RenderingOptions.PaperSize = IronPdf.PdfPaperSize.A4
    renderer.RenderingOptions.MarginTop = 25
    renderer.RenderingOptions.MarginBottom = 25
    renderer.RenderingOptions.MarginLeft = 20
    renderer.RenderingOptions.MarginRight = 20
   
    ' Render the HTML string as a PDF document
    Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(html, "./wwwroot")

    ' Return the PDF file as a response
    Return Results.File(pdf.BinaryData, "application/pdf", "razorViewToPdf.pdf")
End Function)

Imports IronPdf
Imports Microsoft.AspNetCore.Http

app.MapGet("/PrintPdf", Async Function() As Task(Of IResult)
    ' Set your IronPDF license key
    IronPdf.License.LicenseKey = "IRONPDF-MYLICENSE-KEY-1EF01"
    
    ' Enable detailed logging for troubleshooting
    IronPdf.Logging.Logger.LoggingMode = IronPdf.Logging.Logger.LoggingModes.All

    ' Render the Razor view to an HTML string
    Dim html As String = Await RazorTemplateEngine.RenderAsync("Views/Home/Data.cshtml")

    ' Create a new instance of ChromePdfRenderer 
    Dim renderer As New ChromePdfRenderer()
    
    ' Configure rendering options for professional output
    renderer.RenderingOptions.PaperSize = IronPdf.PdfPaperSize.A4
    renderer.RenderingOptions.MarginTop = 25
    renderer.RenderingOptions.MarginBottom = 25
    renderer.RenderingOptions.MarginLeft = 20
    renderer.RenderingOptions.MarginRight = 20
   
    ' Render the HTML string as a PDF document
    Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(html, "./wwwroot")

    ' Return the PDF file as a response
    Return Results.File(pdf.BinaryData, "application/pdf", "razorViewToPdf.pdf")
End Function)

我可以对 PDF 应用哪些渲染选项？

IronPDF 提供广泛的渲染选项。添加页眉和页脚，设置自定义纸张大小，控制页面方向，以及添加水印。 ChromePdfRenderer提供了超过50种属性来定制PDF生成。

如何处理 PDF 生成过程中的错误？

实施错误处理以生成稳健的 PDF：

try
{
    var html = await RazorTemplateEngine.RenderAsync("Views/Home/Data.cshtml");
    var renderer = new ChromePdfRenderer();
    var pdf = renderer.RenderHtmlAsPdf(html, "./wwwroot");
    return Results.File(pdf.BinaryData, "application/pdf", "razorViewToPdf.pdf");
}
catch (Exception ex)
{
    // Log the error details
    IronPdf.Logging.Logger.Log($"PDF generation failed: {ex.Message}");
    return Results.Problem("Failed to generate PDF", statusCode: 500);
}

try
{
    var html = await RazorTemplateEngine.RenderAsync("Views/Home/Data.cshtml");
    var renderer = new ChromePdfRenderer();
    var pdf = renderer.RenderHtmlAsPdf(html, "./wwwroot");
    return Results.File(pdf.BinaryData, "application/pdf", "razorViewToPdf.pdf");
}
catch (Exception ex)
{
    // Log the error details
    IronPdf.Logging.Logger.Log($"PDF generation failed: {ex.Message}");
    return Results.Problem("Failed to generate PDF", statusCode: 500);
}

Imports IronPdf
Imports System.Threading.Tasks

Try
    Dim html = Await RazorTemplateEngine.RenderAsync("Views/Home/Data.cshtml")
    Dim renderer As New ChromePdfRenderer()
    Dim pdf = renderer.RenderHtmlAsPdf(html, "./wwwroot")
    Return Results.File(pdf.BinaryData, "application/pdf", "razorViewToPdf.pdf")
Catch ex As Exception
    ' Log the error details
    IronPdf.Logging.Logger.Log($"PDF generation failed: {ex.Message}")
    Return Results.Problem("Failed to generate PDF", statusCode:=500)
End Try

Imports IronPdf
Imports System.Threading.Tasks

Try
    Dim html = Await RazorTemplateEngine.RenderAsync("Views/Home/Data.cshtml")
    Dim renderer As New ChromePdfRenderer()
    Dim pdf = renderer.RenderHtmlAsPdf(html, "./wwwroot")
    Return Results.File(pdf.BinaryData, "application/pdf", "razorViewToPdf.pdf")
Catch ex As Exception
    ' Log the error details
    IronPdf.Logging.Logger.Log($"PDF generation failed: {ex.Message}")
    Return Results.Problem("Failed to generate PDF", statusCode:=500)
End Try

何时应启用详细日志记录？

确保在开发和故障排除过程中记录详细日志。 IronPDF 的日志记录可以深入了解渲染情况，帮助识别 HTML 解析、资产加载或配置问题。对于生产，请使用自定义日志与应用程序的日志基础架构集成。

我最喜欢的这种库是 IronPDF。它允许快速高效地操作 PDF 文件。它还具有许多有价值的功能，比如导出为 PDF/A 格式和数字签名 PDF 文档。

Milan Jovanovic

微软MVP

查看案例研究

IronOCR 意味着我们每年可以节省 $40,000 的人工处理成本，同时提高生产力，并释放资源用于高影响任务。我强烈推荐它。

Brent Matzelle

首席技术官，OPYN

查看案例研究

为什么需要修改资产链接路径？

导航到视图>共享> _Layout.cshtml。在链接标签中，将"~/"与IronPDF不太兼容。

我还应注意哪些与路径相关的问题？

除了 tilde (~) 路径问题外，还要确保图片来源使用绝对路径或适当的相对引用。对于外部资源，请使用基础 URL，以确保正确加载资产。有关 Azure Blob Storage 图像，请参阅从 Azure Blob Storage 嵌入图像。

静态资产如何影响 PDF 生成？

静态资产（CSS、JavaScript、图像）会影响 PDF 生成的性能和质量。确保资产在渲染过程中可以访问，使用优化的图片，并考虑嵌入关键的 CSS 以加快渲染速度。了解渲染延迟和超时，适用于 JavaScript 较多的内容。

如何测试无头 PDF 生成？

运行项目，生成 PDF 文档。

Visual Studio 显示正在运行的 ASP.NET Core MVC 应用，打开了 Program.cs 并有成功的调试输出

输出 PDF 文件

我的最终 PDF 应该是什么样的？

您的 PDF 应保持所有 Razor View 格式--表格结构、字体、颜色和布局。译文大小要合适，页边要整齐，外观要专业。要验证输出质量，请使用 IronPDF 的光栅化功能以图像形式预览页面。

如何排除常见的 PDF 渲染问题？

常见问题包括样式缺失、布局破损或内容不完整。启用详细的日志记录、验证资产路径并确保 HTML 验证正确。对于复杂的布局，请使用 Chrome 调试工具在转换前预览 HTML。对于特定的渲染问题，请使用 WaitFor delays 以确保内容在渲染前加载。

在哪里可以下载完整的工作示例？

以压缩的 Visual Studio ASP.NET Core Web App（模型-视图-控制器）项目的形式下载完整代码。

点击这里下载项目。

运行示例项目的前提条件是什么？

您需要 Visual Studio 2019 或更高版本和 .NET 6.0 SDK 或更高版本。项目需要互联网连接才能恢复NuGet包。在运行之前更新您的IronPDF许可证密钥到Program.cs中。关于部署，请查看Windows 安装指南以了解其他要求。

如何为我的用例定制示例？

该样本为满足您的特定需求奠定了基础。添加动态数据模型，对频繁生成的 PDF 实施缓存，或与现有的身份验证集成。对于高级应用场景，可探索 async PDF 生成以提高性能，或实施 PDF 压缩以减小文件大小。为文档真实性添加数字签名，或为敏感文档添加密码保护。

常见问题解答

如何在不使用 C# 图形用户界面的情况下将 Razor 视图转换为 PDF？

using Razor.Templating.Core 将 cshtml 文件转换为 HTML，然后使用 IronPDF 的 RenderHtmlAsPdf 方法无头生成 PDF。通过这两步流程，您无需图形用户界面或浏览器窗口即可将Razor视图转换为PDF文档。

将 Razor 视图无头渲染为 PDF 的最快方法是什么？

最快的方法是使用两行代码：首先使用 RazorTemplateEngine.RenderAsync 将 Razor 视图转换为 HTML，然后使用 IronPDF 的 ChromePdfRenderer().RenderHtmlAsPdf(html).SaveAs() 方法创建并保存 PDF 文件。

为什么我应该使用 Razor.Templating.Core 而不是 IronPdf.Extensions.Razor？

Razor.Templating.Core提供真正的无头渲染功能，允许您在没有网页上下文或浏览器窗口的情况下将Razor视图转换为HTML。虽然IronPdf.Extensions.Razor很有用，但它需要网络上下文才能运行，因此Razor.Templating.Core更适合后台服务和控制台应用程序。

无头 PDF 生成需要哪种类型的 ASP.NET Core 项目？

using ASP.NET Core Web App（模型-视图-控制器）项目，该项目提供了必要的 Razor View 基础架构和灵活的部署选项。这种设置与 IronPDF 的后台服务、Azure Functions或控制台应用程序配合使用效果很好。

如何安装 Razor to PDF 转换所需的软件包？

using NuGet 软件包管理器，使用 "Install-Package Razor.Templating.Core "命令安装 Razor.Templating.Core。你还需要在项目中安装 IronPDF，以处理 HTML 到 PDF 的转换步骤。

我能否在云环境中使用这种无头 PDF 生成方法？

是的，IronPDF 的无头 Razor 至 PDF 转换可在云环境中出色地运行，包括 Azure Functions、AWS Lambda 和容器化应用程序，使其成为可扩展文档生成服务的理想选择。

What are the key considerations for styling HTML content for PDF rendering?

When styling HTML for PDF, focus on using print-specific CSS, fixed pixel values, and embedded fonts to ensure consistent rendering, as well as defining margins and breaks appropriately for professional output.

How can static assets impact PDF generation with IronPDF?

Static assets such as CSS, JavaScript, and images influence the quality and speed of PDF rendering. Ensuring assets are accessible and optimized is crucial for consistent performance and visual accuracy.

What should you do if asset paths cause issues in PDF rendering?

Ensure asset paths are correctly formatted, avoiding problematic paths like '~/' and using absolute or properly relative path references to guarantee that all resources load during the rendering process.

What are the prerequisites for running the sample Razor to PDF conversion project?

To run the sample project, you need Visual Studio 2019 or later with the .NET 8.0 SDK and an active internet connection for NuGet package restoration. Additionally, update your IronPDF license key in the code.