When you need pixel-perfect screenshots of HTML content—dashboards, invoices, or reports—Aspose.HTML for .NET gives you fine-grained control through ``. In this guide you’ll learn how to tune resolution (DPI), page size and margins, CSS media type, antialiasing, and output formats (PNG/JPEG/WebP/TIFF) to get consistently sharp images for print and screen.

Key Takeaways

  • Use Converter.ConvertHTML with ImageSaveOptions for reliable HTML → image conversion.
  • Set HorizontalResolution/VerticalResolution to control output DPI; enable UseAntialiasing for crisp edges.
  • Configure PageSetup.AnyPage to define page size and margins (e.g., A4 with 10 mm margins).
  • Choose an image format (Png, Jpeg, Webp, Tiff, Gif, Bmp) to balance quality and file size.
  • Switch Css.MediaType between Screen and Print to honor the right CSS rules.

When to Use ImageSaveOptions

  • Creating printable image proofs of invoices, tickets, and statements.
  • Capturing dashboards and analytics widgets at specific DPI.
  • Generating thumbnails and previews in WebP/JPEG alongside archival PNG/TIFF.

Step-by-Step Guide

1) Load or Create an HTMLDocument

Load an existing HTML file or construct one from a string. The base URI helps resolve relative assets (CSS, images, fonts).

// Load from file
using var document = new Aspose.Html.HTMLDocument("./sample.html");

// Or: create from string (resolves relative URLs against current folder)
string html = "<!DOCTYPE html><html><head><meta charset=\"utf-8\"><title>Demo</title>" +
              "<style>@media print { body { font-size: 12pt } } .badge{background:#1e90ff;color:#fff;padding:6px 10px;border-radius:4px}</style>" +
              "</head><body><h1>Invoice #INV-1001</h1><p class=\"badge\">PAID</p></body></html>";
using var inlineDoc = new Aspose.Html.HTMLDocument(html, ".");

2) Configure ImageSaveOptions

Set DPI, page setup, CSS media type, and target image format.

var options = new Aspose.Html.Saving.ImageSaveOptions(Aspose.Html.Rendering.Image.ImageFormat.Png)
{
    UseAntialiasing = true
};
// DPI
options.HorizontalResolution = 300; // X DPI
options.VerticalResolution   = 300; // Y DPI

// CSS media: use Screen for on-screen styles or Print to honor @media print
options.Css.MediaType = Aspose.Html.Rendering.MediaType.Screen;

// Page setup: A4 with 10 mm margins
var mm = Aspose.Html.Drawing.Length.FromMillimeters;
options.PageSetup.AnyPage = new Aspose.Html.Drawing.Page(
    new Aspose.Html.Drawing.Size(mm(210), mm(297)),
    new Aspose.Html.Drawing.Margin(mm(10), mm(10), mm(10), mm(10))
);

3) Convert HTML to an Image File

Converter.ConvertHTML renders the document according to your options.

Aspose.Html.Converters.Converter.ConvertHTML(inlineDoc, options, "output/page.png");

Complete Example (Compilable)

using System;
using System.IO;
using Aspose.Html;
using Aspose.Html.Converters;
using Aspose.Html.Saving;
using Aspose.Html.Rendering;                // MediaType
using Aspose.Html.Rendering.Image;          // ImageFormat
using Aspose.Html.Drawing;                  // Length, Size, Margin, Page

namespace AsposeHtmlImageSaveOptionsDemo
{
    internal static class Program
    {
        private static void Main(string[] args)
        {
            // Ensure output folder exists
            string outDir = Path.Combine(Directory.GetCurrentDirectory(), "out");
            Directory.CreateDirectory(outDir);

            // Prepare an HTMLDocument: from file path (if provided) or from inline HTML
            HTMLDocument document = null;
            if (args.Length > 0 && File.Exists(args[0]))
            {
                document = new HTMLDocument(args[0]);
            }
            else
            {
                string html = "<!DOCTYPE html>" +
                              "<html><head><meta charset=\\\"utf-8\\\">" +
                              "<title>ImageSaveOptions Demo</title>" +
                              "<style>body{font-family:Arial,Helvetica,sans-serif;margin:24px}" +
                              ".panel{border:1px solid #ddd;border-radius:6px;padding:16px}" +
                              ".badge{display:inline-block;background:#1e90ff;color:#fff;padding:6px 10px;border-radius:4px}" +
                              "@media print { .badge{background:#000} }</style>" +
                              "</head><body>" +
                              "<h1>HTML → Image (Aspose.HTML)</h1>" +
                              "<div class=\\\"panel\\\">" +
                              "<p>This image is rendered using <strong>ImageSaveOptions</strong>.</p>" +
                              "<p><span class=\\\"badge\\\">SCREEN STYLE</span></p>" +
                              "</div></body></html>";
                document = new HTMLDocument(html, ".");
            }

            using (document)
            {
                // --- PNG at 300 DPI, Screen CSS ---
                var options = new ImageSaveOptions(ImageFormat.Png)
                {
                    UseAntialiasing = true
                };
                options.HorizontalResolution = 300;
                options.VerticalResolution   = 300;
                options.Css.MediaType        = MediaType.Screen;

                // Page: A4, 10 mm margins
                var mm = Length.FromMillimeters;
                options.PageSetup.AnyPage = new Page(
                    new Size(mm(210), mm(297)),
                    new Margin(mm(10), mm(10), mm(10), mm(10))
                );

                string pngPath = Path.Combine(outDir, "page.png");
                Converter.ConvertHTML(document, options, pngPath);
                Console.WriteLine($"Saved: {pngPath}");

                // --- JPEG at 150 DPI, Print CSS ---
                var jpegOptions = new ImageSaveOptions(ImageFormat.Jpeg);
                jpegOptions.HorizontalResolution = 150;
                jpegOptions.VerticalResolution   = 150;
                jpegOptions.Css.MediaType        = MediaType.Print;
                // Reuse same page setup
                jpegOptions.PageSetup.AnyPage    = options.PageSetup.AnyPage;

                string jpgPath = Path.Combine(outDir, "page.jpg");
                Converter.ConvertHTML(document, jpegOptions, jpgPath);
                Console.WriteLine($"Saved: {jpgPath}");
            }
        }
    }
}

How to Run

  1. Create a console app:

    dotnet new console -n AsposeHtmlImageSaveOptionsDemo
cd AsposeHtmlImageSaveOptionsDemo

  2. Add the package:

    dotnet add package Aspose.HTML

  3. Replace Program.cs with the Complete Example above.

  4. Run with an HTML file (optional):

    dotnet run -- ../path/to/sample.html

Format Tips

  • PNG: lossless; best for UI, charts, and transparency.
  • JPEG: smallest size for photos and gradients; expect compression artifacts.
  • WebP: modern balance of size and quality; great for web delivery.
  • TIFF: archival or DMS workflows; consider Compression when using TIFF.

Troubleshooting & Best Practices

  • Blurry output → increase DPI via HorizontalResolution/VerticalResolution.
  • Page breaks or clipped content → enlarge Page.Size or margins in PageSetup.AnyPage.
  • Wrong styles → toggle Css.MediaType between Screen and Print.
  • Jagged text → keep UseAntialiasing = true (default).
  • Performance → avoid extreme DPI unless truly needed; cache fonts and external assets.

FAQ

**Q1. What’s the difference between ************ and **********? ImageSaveOptions configures conversion used by Converter.ConvertHTML. ImageRenderingOptions configures an ImageDevice for lower-level rendering. Use ImageSaveOptions for most scenarios.

Q2. How do I control image DPI? Set HorizontalResolution and VerticalResolution (e.g., 300 for print, 96–150 for screen).

Q3. How can I apply print-specific CSS? Set options.Css.MediaType = MediaType.Print; so @media print rules are honored.

Q4. How do I change page size and margins? Assign a Page to options.PageSetup.AnyPage, e.g., A4 with custom Margin.

Q5. Which formats are supported? Png, Jpeg, Bmp, Gif, Tiff, and Webp. Choose based on transparency, file size, and workflow needs.

Conclusion

ImageSaveOptions gives you production-grade control over HTML-to-image output in .NET—DPI, page geometry, CSS media, and formats—so you can deliver sharp, predictable images for both screen and print.

More in this category