Skip to main content

Html2Canvas

Html2Canvas renders a Wisej.NET control, or the whole browser page, to an image and sends it to the server as a System.Drawing.Image. Typical uses:

  • attach a picture of the user's screen to a support ticket or an error report;
  • save a chart, a dashboard or a filled-in form as an image, or put it into a PDF;
  • show a thumbnail preview of a panel.

It wraps html2canvas (version 1.0.0-alpha.11), which runs in the browser and draws the page from its DOM and CSS. It needs no browser extension and no permission prompt, because it doesn't capture the real screen.

Installation​

Add the Wisej-4-Html2Canvas package to your Wisej.NET project:

dotnet add package Wisej-4-Html2Canvas

The package targets .NET Framework 4.8 and .NET 8 or later (including the -windows, Android, iOS and Mac Catalyst targets). There's nothing to drop on the page. Html2Canvas is used only through its static methods, and it creates its own instance per session.

Getting started​

ScreenshotAsync captures a control, and the parameterless overload captures the whole page. Both return a PNG Bitmap.

using Wisej.Web.Ext.Html2Canvas;

// A single control.
private async void buttonSnapshot_Click(object sender, EventArgs e)
{
    var image = await Html2Canvas.ScreenshotAsync(this.panelDashboard);
    this.pictureBoxPreview.Image = image;
}

// The whole browser page, downloaded as a file.
private async void buttonReport_Click(object sender, EventArgs e)
{
    using (var image = await Html2Canvas.ScreenshotAsync())
    using (var stream = new MemoryStream())
    {
        image.Save(stream, System.Drawing.Imaging.ImageFormat.Png);
        stream.Position = 0;
        Application.Download(stream, "screen.png");
    }
}

The Screenshot overloads do the same with a callback. They return at once, and the callback receives the image, or null if it couldn't be decoded:

Html2Canvas.Screenshot(this.panel1, image =>
{
    this.pictureBox1.Image = image;
});
The control must be visible

The image is drawn from what's in the browser, so the target control must be created and visible on the client. A control on a hidden tab page, or a form that isn't shown yet, can't be captured.

Options​

Pass an Html2CanvasOptions to any overload:

FieldWhat it does
BackgroundColorThe canvas background where the page has none. Set it to Color.White for an opaque image that suits JPEG files or printing. null gives a transparent background.
ScaleThe rendering scale. Unless you set it, html2canvas uses the browser's device pixel ratio, so the image is larger on high-DPI screens. Scale = 1 gives a pixel-for-pixel image, and Scale = 2 a sharper, larger one.
var options = new Html2CanvasOptions { BackgroundColor = Color.White, Scale = 2 };
var image = await Html2Canvas.ScreenshotAsync(this.chartPanel, options);

What gets captured​

html2canvas doesn't take a real screenshot. It re-draws the page from the DOM and the computed CSS, so some content can be missing or look different:

  • Cross-origin content. Images from other domains are drawn only if their server allows CORS (the extension always sets useCORS). Otherwise they're left out. The content of <iframe>s is never captured, so embedded pages, PDF viewers and videos come out blank.
  • Native plugins and video. <video> frames, <canvas> elements drawn with WebGL, and browser-native widgets may be empty or show only their placeholder.
  • Newer CSS. The bundled html2canvas release predates several CSS features. Recent effects such as backdrop-filter, some blend modes, and complex clip-path or mask settings may be ignored.
  • Size and time. Capturing the whole page of a large application can take a noticeable moment, and at a high Scale the PNG can be several megabytes before it's sent to the server.
Capture the smallest control that works

Capture the panel you need rather than the whole page. It's faster, the image is smaller, and it's less likely to include content (such as an <iframe>) that html2canvas can't draw.

Privacy

A capture of the whole page includes whatever the user has on screen in your application, including personal data in other panels. Tell users what's included before you attach a capture to a ticket, and store captures with the same care as the data they show.

Error handling​

When the browser fails to render the image, ScreenshotAsync returns a faulted task, so wrap the await in try/catch. With the callback overloads the error surfaces when the response is processed, not at the Screenshot call. The callback receives null when the returned data can't be decoded as an image.

API reference​