How to Convert ASP HTML to PDF in .NET Core Using IronPDF

Which Installation Method Should I Use?

The quickest way to add IronPDF to your ASP.NET project for converting HTML to PDF is through the NuGet Package Manager in Visual Studio. Right-click on your project in Solution Explorer, select "Manage NuGet Packages," and search for IronPDF. Click Install on the latest version to add it to your project. For detailed installation instructions, see the IronPDF installation guide. Alternative installation methods include the Windows installer or Docker deployment.

Install-Package IronPdf

Which Namespaces Are Required?

Once installed, add the IronPDF namespace to any C# file where you'll be working with PDF generation:

using IronPdf;

using IronPdf;

This simple import statement gives you access to all of IronPDF's functionality, including the ChromePdfRenderer class for HTML conversion and various configuration options for customizing your PDF output. You can also explore F# integration or VB.NET usage if you're working with alternative .NET languages.

How Do I Configure IronPDF for My Environment?

For most ASP.NET Core applications, IronPDF works immediately after installation without additional configuration. However, you can set global options in your Program.cs or Startup.cs file:

// Optional: Configure IronPDF settings
Installation.TempFolderPath = @"C:\Temp\IronPdf\";
Installation.LinuxAndDockerDependenciesAutoConfig = true;

// Configure logging for debugging
Installation.LoggingMode = IronPdf.Logging.LoggingMode.All;
Installation.LogFilePath = "IronPdfLog.log";

// For Azure deployments
Installation.AzureQuickDeployment = true;

// Optional: Configure IronPDF settings
Installation.TempFolderPath = @"C:\Temp\IronPdf\";
Installation.LinuxAndDockerDependenciesAutoConfig = true;

// Configure logging for debugging
Installation.LoggingMode = IronPdf.Logging.LoggingMode.All;
Installation.LogFilePath = "IronPdfLog.log";

// For Azure deployments
Installation.AzureQuickDeployment = true;

These configuration options help improve IronPDF for your specific hosting environment, whether you're running on Windows, Linux, or in Docker containers. For Azure deployments, enable AzureQuickDeployment for optimal performance. When deploying to AWS Lambda, consider using containerized deployments. Ensure both the script and application files don't reside in the same directory to prevent conflicts. For production environments, implement custom logging to monitor PDF generation operations.

What Does the PDF Output Look Like?

How Do I Include CSS Styling and Images?

IronPDF fully supports CSS styling and can embed images from various sources when converting HTML to PDF. The PDF converter handles HTML elements with complete fidelity, including various HTML tags and image URLs. It supports web fonts, SVG graphics, and even base64 encoded images:

var html = @"
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        h1 { color: #2c3e50; border-bottom: 2px solid #3498db; }
        .highlight { background-color: #f1c40f; padding: 5px; }
        .table { width: 100%; border-collapse: collapse; }
        .table td { border: 1px solid #ddd; padding: 8px; }
    </style>
    <h1>Monthly Report</h1>
    <p>This HTML document includes <span class='highlight'>highlighted text</span> and styling.</p>
    <table class='table'>
        <tr><td>Product</td><td>Sales</td></tr>
        <tr><td>Widget A</td><td>$1,234</td></tr>
    </table>
    <img src='data:image/png;base64,iVBORw0KGgoAAAANS...' alt='Logo' />";

var renderer = new ChromePdfRenderer();

// Set base URL for relative paths
renderer.RenderingOptions.BaseUrl = "___PROTECTED_URL_90___";

// Enable JavaScript execution
renderer.RenderingOptions.EnableJavaScript = true;

var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("styled-report.pdf");

var html = @"
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        h1 { color: #2c3e50; border-bottom: 2px solid #3498db; }
        .highlight { background-color: #f1c40f; padding: 5px; }
        .table { width: 100%; border-collapse: collapse; }
        .table td { border: 1px solid #ddd; padding: 8px; }
    </style>
    <h1>Monthly Report</h1>
    <p>This HTML document includes <span class='highlight'>highlighted text</span> and styling.</p>
    <table class='table'>
        <tr><td>Product</td><td>Sales</td></tr>
        <tr><td>Widget A</td><td>$1,234</td></tr>
    </table>
    <img src='data:image/png;base64,iVBORw0KGgoAAAANS...' alt='Logo' />";

var renderer = new ChromePdfRenderer();

// Set base URL for relative paths
renderer.RenderingOptions.BaseUrl = "___PROTECTED_URL_90___";

// Enable JavaScript execution
renderer.RenderingOptions.EnableJavaScript = true;

var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("styled-report.pdf");

The renderer processes inline styles, CSS files, and even base64-encoded images. This ensures your PDF pages maintain the exact appearance of your HTML content, including modern CSS3 features like flexbox and grid layouts. The HTML to PDF conversion preserves all HTML tags and their styling without generating blank pages. For complex layouts, consider using Bootstrap compatibility or implementing custom page breaks.

How Do I Convert Controller Views?

In your ASP.NET Core controller, you can render a view to HTML and then convert it to a PDF document using IronPDF's effective PDF library rendering capabilities. This approach works with both MVC Core and MVC Framework applications:

[HttpGet]
public async Task<IActionResult> DownloadPdf()
{
    var invoiceModel = new InvoiceModel
    {
        InvoiceNumber = 12345,
        Date = DateTime.Now,
        CustomerName = "Acme Corporation",
        Items = new List<InvoiceItem>
        {
            new InvoiceItem { Description = "Service", Quantity = 1, Price = 100.0 },
            new InvoiceItem { Description = "Support", Quantity = 2, Price = 50.0 }
        },
        Total = 200.0
    };

    // Render the view to HTML string
    var htmlContent = await RenderViewToString("Invoice", invoiceModel);

    // Convert HTML to PDF with custom settings
    var renderer = new ChromePdfRenderer();
    renderer.RenderingOptions.PaperSize = PdfPaperSize.Letter;
    renderer.RenderingOptions.PrintHtmlBackgrounds = true;

    // Add header with invoice number
    renderer.RenderingOptions.TextHeader.CenterText = "Invoice #" + invoiceModel.InvoiceNumber;
    renderer.RenderingOptions.TextHeader.DrawDividerLine = true;

    var pdf = renderer.RenderHtmlAsPdf(htmlContent);

    // Apply security settings if needed
    pdf.SecuritySettings.AllowUserPrinting = true;
    pdf.SecuritySettings.AllowUserCopyPasteContent = false;

    // Return PDF to browser
    var contentType = "application/pdf";
    var fileName = $"invoice_{invoiceModel.InvoiceNumber}_{DateTime.Now:yyyyMMdd}.pdf";
    return File(pdf.BinaryData, contentType, fileName);
}

private async Task<string> RenderViewToString(string viewName, object model)
{
    ViewData.Model = model;
    using (var writer = new StringWriter())
    {
        var viewResult = viewEngine.FindView(ControllerContext, viewName, false);

        if (!viewResult.Success)
        {
            throw new ArgumentException($"View '{viewName}' not found");
        }

        var viewContext = new ViewContext(
            ControllerContext,
            viewResult.View,
            ViewData,
            TempData,
            writer,
            new HtmlHelperOptions()
        );

        await viewResult.View.RenderAsync(viewContext);
        return writer.GetStringBuilder().ToString();
    }
}

[HttpGet]
public async Task<IActionResult> DownloadPdf()
{
    var invoiceModel = new InvoiceModel
    {
        InvoiceNumber = 12345,
        Date = DateTime.Now,
        CustomerName = "Acme Corporation",
        Items = new List<InvoiceItem>
        {
            new InvoiceItem { Description = "Service", Quantity = 1, Price = 100.0 },
            new InvoiceItem { Description = "Support", Quantity = 2, Price = 50.0 }
        },
        Total = 200.0
    };

    // Render the view to HTML string
    var htmlContent = await RenderViewToString("Invoice", invoiceModel);

    // Convert HTML to PDF with custom settings
    var renderer = new ChromePdfRenderer();
    renderer.RenderingOptions.PaperSize = PdfPaperSize.Letter;
    renderer.RenderingOptions.PrintHtmlBackgrounds = true;

    // Add header with invoice number
    renderer.RenderingOptions.TextHeader.CenterText = "Invoice #" + invoiceModel.InvoiceNumber;
    renderer.RenderingOptions.TextHeader.DrawDividerLine = true;

    var pdf = renderer.RenderHtmlAsPdf(htmlContent);

    // Apply security settings if needed
    pdf.SecuritySettings.AllowUserPrinting = true;
    pdf.SecuritySettings.AllowUserCopyPasteContent = false;

    // Return PDF to browser
    var contentType = "application/pdf";
    var fileName = $"invoice_{invoiceModel.InvoiceNumber}_{DateTime.Now:yyyyMMdd}.pdf";
    return File(pdf.BinaryData, contentType, fileName);
}

private async Task<string> RenderViewToString(string viewName, object model)
{
    ViewData.Model = model;
    using (var writer = new StringWriter())
    {
        var viewResult = viewEngine.FindView(ControllerContext, viewName, false);

        if (!viewResult.Success)
        {
            throw new ArgumentException($"View '{viewName}' not found");
        }

        var viewContext = new ViewContext(
            ControllerContext,
            viewResult.View,
            ViewData,
            TempData,
            writer,
            new HtmlHelperOptions()
        );

        await viewResult.View.RenderAsync(viewContext);
        return writer.GetStringBuilder().ToString();
    }
}

This approach renders your Razor view to an HTML string first, then converts it to PDF. The PDF is returned as a file download to the user's browser with an appropriate filename. This works smoothly whether you're converting an ASPX file or modern Razor views. For headless conversion scenarios, consider using Razor.Templating.Core.

What Does the Generated PDF Look Like?

How Do I Convert URLs to PDF?

For existing web pages, you can use IronPDF as an effective HTML to PDF converter to transform any specified URL directly into PDF files. Simply provide an HTTP or HTTPS address as the URL parameter. This method supports cookies and custom HTTP headers for authenticated requests:

[HttpGet]
public IActionResult GeneratePdfFromUrl()
{
    var renderer = new ChromePdfRenderer();

    // Configure for web page rendering
    renderer.RenderingOptions.WaitFor.RenderDelay = 2000; // Wait for dynamic content
    renderer.RenderingOptions.ViewportWidth = 1920; // Desktop viewport

    // Add custom headers if needed
    renderer.RenderingOptions.HttpHeaders.Add("Authorization", "Bearer your-token");

    // Handle cookies for authentication
    renderer.RenderingOptions.Cookies.Add(new Cookie
    {
        Name = "session_id",
        Value = Request.Cookies["session_id"],
        Domain = "yourdomain.com"
    });

    // Convert a specified URL to PDF document
    var pdf = renderer.RenderUrlAsPdf("___PROTECTED_URL_91___");

    // Improve file size
    pdf.CompressImages(90);

    // Stream the PDF file to the browser
    return File(pdf.BinaryData, "application/pdf", "webpage.pdf");
}

[HttpGet]
public IActionResult GeneratePdfFromUrl()
{
    var renderer = new ChromePdfRenderer();

    // Configure for web page rendering
    renderer.RenderingOptions.WaitFor.RenderDelay = 2000; // Wait for dynamic content
    renderer.RenderingOptions.ViewportWidth = 1920; // Desktop viewport

    // Add custom headers if needed
    renderer.RenderingOptions.HttpHeaders.Add("Authorization", "Bearer your-token");

    // Handle cookies for authentication
    renderer.RenderingOptions.Cookies.Add(new Cookie
    {
        Name = "session_id",
        Value = Request.Cookies["session_id"],
        Domain = "yourdomain.com"
    });

    // Convert a specified URL to PDF document
    var pdf = renderer.RenderUrlAsPdf("___PROTECTED_URL_91___");

    // Improve file size
    pdf.CompressImages(90);

    // Stream the PDF file to the browser
    return File(pdf.BinaryData, "application/pdf", "webpage.pdf");
}

This method is particularly useful when you already have well-formatted web pages and want to offer them as downloadable PDF versions. The .NET library handles all external resources, including stylesheets, scripts, and images, ensuring complete HTML rendering. The converter returns an appropriate HTTP status code if it encounters an invalid URL. For JavaScript-heavy sites, adjust the render delay or use WaitFor conditions.

What Is the Result from URL Conversion?

How Do I Handle Authenticated Pages?

When converting authenticated pages with .NET forms authentication or other security mechanisms, you can pass cookies or headers to maintain the user's session. This prevents redirection to a login screen during PDF conversion. IronPDF supports various authentication methods including TLS authentication and Kerberos:

var renderer = new ChromePdfRenderer();

// Set cookies for authenticated requests with user credentials
renderer.RenderingOptions.CustomCookies.Add("auth_token", Request.Cookies["auth_token"]);
renderer.RenderingOptions.CustomCookies.Add("session_id", Request.Cookies["session_id"]);

// Add authentication headers
renderer.RenderingOptions.HttpHeaders.Add("X-CSRF-Token", Request.Headers["X-CSRF-Token"]);

// For basic authentication
renderer.RenderingOptions.HttpLoginCredentials = new HttpLoginCredentials
{
    Username = "apiuser",
    Password = "securepassword"
};

// Configure timeout for slow-loading authenticated pages
renderer.RenderingOptions.RequestTimeout = 60000; // 60 seconds

// Convert protected web pages to PDF
var pdf = renderer.RenderUrlAsPdf("___PROTECTED_URL_92___");

// Add metadata for tracking
pdf.MetaData.Author = User.Identity.Name;
pdf.MetaData.CreationDate = DateTime.Now;

pdf.SaveAs("secure-report.pdf");

var renderer = new ChromePdfRenderer();

// Set cookies for authenticated requests with user credentials
renderer.RenderingOptions.CustomCookies.Add("auth_token", Request.Cookies["auth_token"]);
renderer.RenderingOptions.CustomCookies.Add("session_id", Request.Cookies["session_id"]);

// Add authentication headers
renderer.RenderingOptions.HttpHeaders.Add("X-CSRF-Token", Request.Headers["X-CSRF-Token"]);

// For basic authentication
renderer.RenderingOptions.HttpLoginCredentials = new HttpLoginCredentials
{
    Username = "apiuser",
    Password = "securepassword"
};

// Configure timeout for slow-loading authenticated pages
renderer.RenderingOptions.RequestTimeout = 60000; // 60 seconds

// Convert protected web pages to PDF
var pdf = renderer.RenderUrlAsPdf("___PROTECTED_URL_92___");

// Add metadata for tracking
pdf.MetaData.Author = User.Identity.Name;
pdf.MetaData.CreationDate = DateTime.Now;

pdf.SaveAs("secure-report.pdf");

This ensures that protected HTML content can be converted to PDF files while maintaining security. The PDF conversion process respects your application's authentication, preventing unauthorized access to sensitive documents. You can pass username and password arguments when needed for basic authentication scenarios. For SSO implementations, consider using request context management.## How Can I Customize PDF Output?

IronPDF offers extensive customization options as a complete PDF converter to control how your PDF documents are generated from HTML documents. These settings help you create professional PDF files that meet specific requirements for page layout and formatting. Explore the full range of rendering options available.

How Do I Set Page Size and Margins?

Control paper size and margins precisely for professional document layouts:

var renderer = new ChromePdfRenderer();

// Set default page size for PDF pages
renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;
renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Portrait;

// Control page width and margins for the PDF document
renderer.RenderingOptions.MarginTop = 25;
renderer.RenderingOptions.MarginBottom = 25;
renderer.RenderingOptions.MarginLeft = 20;
renderer.RenderingOptions.MarginRight = 20;

// Or use custom paper size
renderer.RenderingOptions.SetCustomPaperSizeInInches(8.5, 11);

// Control first page differently
renderer.RenderingOptions.FirstPageNumber = 1;

// Enable print-friendly CSS
renderer.RenderingOptions.CssMediaType = PdfCssMediaType.Print;

// Enable background colors and images
renderer.RenderingOptions.PrintHtmlBackgrounds = true;

var renderer = new ChromePdfRenderer();

// Set default page size for PDF pages
renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;
renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Portrait;

// Control page width and margins for the PDF document
renderer.RenderingOptions.MarginTop = 25;
renderer.RenderingOptions.MarginBottom = 25;
renderer.RenderingOptions.MarginLeft = 20;
renderer.RenderingOptions.MarginRight = 20;

// Or use custom paper size
renderer.RenderingOptions.SetCustomPaperSizeInInches(8.5, 11);

// Control first page differently
renderer.RenderingOptions.FirstPageNumber = 1;

// Enable print-friendly CSS
renderer.RenderingOptions.CssMediaType = PdfCssMediaType.Print;

// Enable background colors and images
renderer.RenderingOptions.PrintHtmlBackgrounds = true;

These settings control the physical layout of your PDF pages, including both odd and even pages. You can choose from standard paper sizes or define custom dimensions, set portrait or environment orientation, and adjust margins to match your design requirements for multiple pages. The graphics template system ensures consistent styling across pages. For specific orientation needs, explore page rotation options.

What Do Customized PDFs Look Like?

How Do I Add Headers and Footers?

Adding consistent headers and footers improves the professional appearance of your PDF documents when converting HTML documents. IronPDF supports both text headers and HTML headers:

// Add text-based header and footer
renderer.RenderingOptions.TextHeader = new TextHeaderFooter()
{
    CenterText = "Company Report",
    LeftText = "{date}",
    RightText = "Confidential",
    FontSize = 12,
    FontFamily = "Arial",
    DrawDividerLine = true
};

renderer.RenderingOptions.TextFooter = new TextHeaderFooter()
{
    CenterText = "Page {page} of {total-pages}",
    LeftText = "© 2024 Company Name",
    RightText = "{time}",
    FontSize = 10,
    DrawDividerLine = true
};

// Or use HTML headers for more complex layouts
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
    HtmlFragment = @"
        <div style='display: flex; justify-content: space-between; align-items: center;'>
            <img src='logo.png' height='30' />
            <h2>Monthly Report</h2>
            <span>{date}</span>
        </div>",
    MaxHeight = 50,
    DrawDividerLine = true
};

renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
    HtmlFragment = @"
        <div style='text-align: center; font-size: 12px; color: #666;'>
            <p>Page {page} of {total-pages} | Document ID: {pdf-title}</p>
        </div>",
    MaxHeight = 30,
    LoadStylesAndCSSFromMainHtmlDocument = true
};

// Add text-based header and footer
renderer.RenderingOptions.TextHeader = new TextHeaderFooter()
{
    CenterText = "Company Report",
    LeftText = "{date}",
    RightText = "Confidential",
    FontSize = 12,
    FontFamily = "Arial",
    DrawDividerLine = true
};

renderer.RenderingOptions.TextFooter = new TextHeaderFooter()
{
    CenterText = "Page {page} of {total-pages}",
    LeftText = "© 2024 Company Name",
    RightText = "{time}",
    FontSize = 10,
    DrawDividerLine = true
};

// Or use HTML headers for more complex layouts
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
    HtmlFragment = @"
        <div style='display: flex; justify-content: space-between; align-items: center;'>
            <img src='logo.png' height='30' />
            <h2>Monthly Report</h2>
            <span>{date}</span>
        </div>",
    MaxHeight = 50,
    DrawDividerLine = true
};

renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
    HtmlFragment = @"
        <div style='text-align: center; font-size: 12px; color: #666;'>
            <p>Page {page} of {total-pages} | Document ID: {pdf-title}</p>
        </div>",
    MaxHeight = 30,
    LoadStylesAndCSSFromMainHtmlDocument = true
};

Headers and footers support HTML elements and formatting with special placeholders for page numbers, dates, and other dynamic content across all PDF pages. The following code demonstrates how to add professional headers to your dynamically generated document or existing PDF documents. You can also apply headers to specific pages for more control.