Renderers – Render HTML, MHTML, EPUB, and SVG in C#

Use renderers directly when Document.RenderTo() is not enough. HtmlRenderer, SvgRenderer, MhtmlRenderer, and EpubRenderer can render source-specific documents to an output device, merge multiple sources, and control rendering timeout.

Renderers

The Aspose.Html.Rendering namespace consists of numerous renderer objects and appropriate low-level options classes, which are responsible for rendering documents into IDevice implementation. Aspose.HTML for .NET API provides the following realization of renderers: HtmlRenderer, SvgRenderer, MhtmlRenderer, and EpubRenderer, which are used to render HTML, SVG, MHTML, and EPUB documents, respectively.

While the RenderTo() method of the Document class gives you the ability to send a single document to the output rendering device, using the Renderer instances directly, you can send multiple files at once. You can merge HTML, MHTML, EPUB, and SVG documents and apply rendering options to control the output file.

The current article describes supported scenarios of HTML-based file conversion & merging to other popular formats using Render() methods of the Renderer class.

HtmlRenderer

Usage of the HtmlRenderer class to render HTML files to other popular formats – is one more way to convert HTML by customizing the rendering options and controlling the rendering process’s output. Let’s look at using the HtmlRenderer class to render HTML to PDF with custom rendering options:

1. Initialize an HTML document. Use one of the HTMLDocument() constructors to create an HTMLDocument instance.
2. Create a new HtmlRenderer object.
3. Create the instance of the PdfRenderingOptions and set custom options for the output PDF document. In the example, we specify the AnyPage property of the PageSetup class that sets a new Page object with a page size of 600 pixels by 200 pixels and the Encryption property that identifies the user and owner passwords, allowed permissions, and encryption algorithm for the output PDF file.
4. Use PdfDevice(options, savePath) constructor to create an object of the PdfDevice class.
5. And finally, call the Render(device, document) method to render the HTML document to the output PDF file with the specified rendering options.

// Render HTML to PDF with custom page settings using C#

// Prepare a path to a source HTML file
string documentPath = Path.Combine(DataDir, "file.html");

// Initialize an HTML document from the file
using HTMLDocument document = new HTMLDocument(documentPath);

// Create an instance of HTML Renderer
using HtmlRenderer renderer = new HtmlRenderer();

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "convert-html-options.pdf");

// Create the instance of Rendering Options and set a custom page-size
PdfRenderingOptions options = new PdfRenderingOptions();
options.PageSetup.AnyPage = new Page(new Size(600, 200));
options.Encryption = new PdfEncryptionInfo(
       "user_pwd",
       "owner_pwd",
       PdfPermissions.PrintDocument,
       PdfEncryptionAlgorithm.RC4_128);

// Create an instance of PDF device
using PdfDevice device = new PdfDevice(options, savePath);

// Render HTML to PDF
renderer.Render(device, document);

Rendering options give you additional control over the rendering process. To learn more about them, please read the Rendering options article.

To learn more about rendering process, please read the Rendering Device article.

If you are interested in how to use rendering options to resize document pages to the size of the content and vice versa, please visit the article How to Resize Document During Conversion from HTML?

SvgRenderer

The SvgRenderer allows you to render SVG files to other file formats, such as PDF, XPS, DOCX, and image formats. With this, you can customize the output file using various rendering options. The following example demonstrates how to use SvgRenderer class to render SVG to PDF with a custom page size specifying:

1. Initialize an SVG document. Use one of the SVGDocument() constructors to create an SVGDocument instance.
2. Create a new SvgRenderer object.
3. Create an instance of the PdfRenderingOptions and set custom options for the output PDF document. In the example, we specify the PageSetup.AnyPage property that sets a new Page object with a page size of 600x500 pixels.
4. Use the PdfDevice(options, savePath) constructor to create an object of the PdfDevice class.
5. And finally, call the Render(device, document) method to render the SVG document to the output PDF file with the specified rendering options.

// Render SVG to PDF using C#

// Initialize an SVG document from the file
using SVGDocument document = new SVGDocument(Path.Combine(DataDir, "shapes.svg"));

// Create an instance of SVG Renderer
using SvgRenderer renderer = new SvgRenderer();

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "rendering-svg.pdf");

// Create the instance of Rendering Options and set a custom page-size
PdfRenderingOptions options = new PdfRenderingOptions();
options.PageSetup.AnyPage = new Page(new Size(600, 500));

// Create an instance of the Pdfdevice class
using PdfDevice device = new PdfDevice(options, savePath);

// Render SVG to PDF
renderer.Render(device, document);

MhtmlRenderer

The following example demonstrates how to convert MHTML to PDF with the rendering options specifying using the MhtmlRenderer class:

1. Open an existing MHTML document.
2. Create an instance of MhtmlRenderer using the MhtmlRenderer() constructor.
3. Initialize the PdfRenderingOptions class and set rendering options.
4. Create an instance of the PdfDevice class.
5. Call the Render(device, stream) method to render MHTML to PDF.

// Convert MHTML to PDF with custom page settings using C#

// Open an existing MHTML file for reading
using FileStream stream = File.OpenRead(DataDir + "sample.mht");

// Create an instance of MHTML Renderer
using MhtmlRenderer renderer = new MhtmlRenderer();

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "convert-mhtml-options.pdf");

// Create the instance of Rendering Options and set a custom page-size and background color
PdfRenderingOptions options = new PdfRenderingOptions();
options.PageSetup.AnyPage = new Page(new Size(600, 200));
options.BackgroundColor = System.Drawing.Color.Azure;

// Create an instance of PDF device
using PdfDevice device = new PdfDevice(options, savePath);

// Convert MHTML to PDF
renderer.Render(device, stream);

EpubRenderer

The EpubRenderer class allows you to convert EPUB files to other formats such as PDF, XPS, DOCX, and images. The following C# examples shows how to convert EPUB to DOCX with a custom page size setting:

1. Open an existing EPUB file.
2. Create an instance of EpubRenderer class.
3. Initialize the DocRenderingOptions class and set rendering options.
4. Create an instance of the DocDevice class.
5. Call the Render(device, stream) method to render EPUB to DOCX.

// Convert EPUB to DOCX with custom page size using C#

// Open an existing EPUB file for reading
using FileStream stream = File.OpenRead(DataDir + "input.epub");

// Create an instance of EPUB Renderer
using EpubRenderer renderer = new EpubRenderer();

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "convert-epub-options.docx");

// Create the instance of Rendering Options and set a custom page-size
DocRenderingOptions options = new DocRenderingOptions();
options.PageSetup.AnyPage = new Page(new Size(800, 400));

// Create an instance of the DocDevice class
using DocDevice device = new DocDevice(options, savePath);

// Render EPUB to DOCX
renderer.Render(device, stream);

Merge HTML

Aspose.HTML for .NET API provides the Renderer class for rendering and merging HTML, MHTML, EPUB, and SVG documents to popular formats. While the RenderTo() method gives you the ability to send a single document to the output rendering device, using the Renderer instances directly, you can send multiple files at once. HtmlRenderer, SvgRenderer, MhtmlRenderer, and EpubRenderer can merge HTML, SVG, MHTML, and EPUB documents, respectively. The next example demonstrates how to use HtmlRenderer to render multiple HTML documents.

To merge HTML documents:

1. Load the HTML documents that should be rendered into one output file.
2. Create the target device, such as PdfDevice, with the output path.
3. Create an HtmlRenderer instance.
4. Pass the device and documents to renderer.Render().
5. Save the merged result as one PDF document.

// Merge HTML to PDF using C#

// Prepare HTML code
string code1 = @"<br><span style='color: green'>Hello, World!!</span>";
string code2 = @"<br><span style='color: blue'>Hello, World!!</span>";
string code3 = @"<br><span style='color: red'>Hello, World!!</span>";

// Create three HTML documents to merge later
using HTMLDocument document1 = new HTMLDocument(code1, ".");
using HTMLDocument document2 = new HTMLDocument(code2, ".");
using HTMLDocument document3 = new HTMLDocument(code3, ".");

// Create an instance of HTML Renderer
using HtmlRenderer renderer = new HtmlRenderer();

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "merge-html.pdf");

// Create an instance of PDF device
using PdfDevice device = new PdfDevice(savePath);

// Merge all HTML documents into PDF
renderer.Render(device, document1, document2, document3);

Set Timeout

One more important feature that is available for renderers is timeout. You can use it to specify how long you are ready to wait for internal processes related to a document lifecycle to be completed, such as resource loading and active timers. You can specify an infinite waiting period, but if the document contains a script with an endless loop, the render operation may wait indefinitely.

To render with a timeout:

1. Create or load the source document.
2. Create the renderer and output device.
3. Choose a TimeSpan timeout value.
4. Call renderer.Render(device, timeout, document).
5. Handle the partially rendered output if the timeout is reached.

The example below demonstrates how to use the timeout parameter:

// Render HTML to PDF with timeout settings using C#

// Prepare HTML code
string code = @"
<script>
    var count = 0;
    setInterval(function()
        {
            var element = document.createElement('div');
            var message = (++count) + '. ' + 'Hello, World!! I know how to use Renderers!';
            var text = document.createTextNode(message);
            element.appendChild(text);
            document.body.appendChild(element);
        }, 1000);
</script>";

// Initialize an HTML document based on prepared HTML code
using HTMLDocument document = new HTMLDocument(code, ".");

// Create an instance of HTML Renderer
using HtmlRenderer renderer = new HtmlRenderer();

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "output-timeout.pdf");

// Create an instance of the PdfDevice class
using PdfDevice device = new PdfDevice(savePath);

// Render HTML to PDF
renderer.Render(device, TimeSpan.FromSeconds(5), document);

In this example, we create an HTML document that adds a new <div> element every second with a sequential number and the message “Hello, World!!” We use the TimeSpan parameter in the Render(device, timeout, document) method to set timeout. This setting specifies the maximum time the renderer will spend rendering the document. In this case, the total time is set to 5 seconds. If the renderer has not generated a document within the specified time, it will stop and render a partially rendered document. Running this example, you will get a document with five lines of “Hello, World!! I know how to use Renderers!” message, as follows:

Common Renderer Mistakes

• Using a renderer when Document.RenderTo() is enough – use Document.RenderTo() for a single loaded document and direct rendering. Use HtmlRenderer, SvgRenderer, MhtmlRenderer, or EpubRenderer when you need source-specific rendering, merging, streams, or timeout control.
• Choosing the wrong renderer for the source document – match the renderer to the input type: HtmlRenderer for HTML, SvgRenderer for SVG, MhtmlRenderer for MHTML, and EpubRenderer for EPUB.
• Choosing the wrong device for the output file – match the device to the target format: PdfDevice for PDF, ImageDevice for raster images, XpsDevice for XPS, and DocDevice for DOCX.
• Leaving timeout unlimited for dynamic documents – pass a TimeSpan when rendering pages with scripts, timers, or remote resources, so the operation cannot wait indefinitely.
• Merging unrelated document types in one workflow – keep the renderer aligned with the source collection, and use the output device only to define the final format.

Related Rendering Guides

• Rendering Devices in C#
• Rendering Options in C#
• Convert HTML to PDF in C#
• Fine-Tune HTML Conversion in C#

The complete C# examples and data files are available in the Aspose.HTML for .NET GitHub repository.