How to: Generate a Thumbnail Image from a Worksheet

Jan 27, 2022
4 minutes to read

The Spreadsheet Document API allows you to create thumbnails for worksheets. A thumbnail is a small image that you can insert into a document, presentation, or website to display a preview of worksheet content.

Call the WorksheetExtensions.CreateThumbnail extension method for a Worksheet object to generate a thumbnail image of the specified size from a worksheet. Pass an ImageFileFormat enumeration member to this method to set the thumbnail image format.

Important

The WorksheetExtensions class is defined in the DevExpress.Docs.v25.2.dll assembly. Add this assembly to your project to use worksheet extensions. You need a license for the DevExpress Office File API Subscription or DevExpress Universal Subscription to use this assembly in production code.

The thumbnail image includes the following worksheet elements:

Cells from “A1” to the bottom-right cell that contains data or formatting (excluding hidden rows and columns)
Worksheet row and column headers

If a worksheet is bigger than the thumbnail, the worksheet is cropped to fit this thumbnail. If the worksheet is smaller, the remaining space is filled with the default background color.

The code sample below generates a thumbnail from a worksheet.

C#
VB.NET

csharp

using DevExpress.Spreadsheet;
// ...

// Create a new Workbook object.
using (Workbook workbook = new Workbook())
{
    // Load a workbook from a file.
    workbook.LoadDocument("TopTradingPartners.xlsx", DocumentFormat.Xlsx);

    // Access an active worksheet.
    Worksheet worksheet = workbook.Worksheets.ActiveWorksheet;

    // Generate a thumbnail.
    if (worksheet != null)
        worksheet.CreateThumbnail("Worksheet_Thumbnail.png", ImageFileFormat.Png, 1600, 900);
}

Imports DevExpress.Spreadsheet
' ...

' Create a new Workbook object.
Using workbook As New Workbook()
    ' Load a workbook from a file.
    workbook.LoadDocument("TopTradingPartners.xlsx", DocumentFormat.Xlsx)

    ' Access an active worksheet.
    Dim worksheet As Worksheet = workbook.Worksheets.ActiveWorksheet

    ' Generate a thumbnail.
    If worksheet IsNot Nothing Then
        worksheet.CreateThumbnail("Worksheet_Thumbnail.png", ImageFileFormat.Png, 1600, 900)
    End If
End Using

Customize Thumbnail Settings

Create a WorksheetThumbnailOptions class instance and pass it to the WorksheetExtensions.CreateThumbnail method to specify thumbnail options. The following options are available:

WorksheetThumbnailOptions Property	Description
BackgroundColor	Specifies the background color for the output image.
Resolution	Specifies the image resolution (in DPI).
Scale	Specifies how to scale content of a worksheet before it is saved as an image. The Scale property has no effect if the Stretch property is set to true.
Stretch	Specifies whether a worksheet is stretched to fit the output image size.
ColumnOffset	Specifies the index of the column from which to start thumbnail generation.
RowOffset	Specifies the index of the row from which to start thumbnail generation.

The code sample below specifies thumbnail options and generates a thumbnail.

C#
VB.NET

csharp

using DevExpress.Spreadsheet;
using System.Drawing;
// ...

// Create a new Workbook object.
using (Workbook workbook = new Workbook())
{
    // Load a workbook from a file.
    workbook.LoadDocument("TopTradingPartners.xlsx", DocumentFormat.Xlsx);

    // Access an active worksheet.
    Worksheet worksheet = workbook.Worksheets.ActiveWorksheet;

    // Specify thumbnail options.
    var thumbnailOptions = new WorksheetThumbnailOptions
    {
        Resolution = 192,
        Scale = 80,
        ColumnOffset = 1,
        RowOffset = 1,
        BackgroundColor = Color.FromArgb(0xF2, 0xF2, 0xF2)
    };

    // Create a thumbnail image.
    if (worksheet != null)
        worksheet.CreateThumbnail("Worksheet_Thumbnail.png", ImageFileFormat.Png, 1600, 900, thumbnailOptions);
}

Imports DevExpress.Spreadsheet
Imports System.Drawing
' ...

' Create a new Workbook object.
Using workbook As New Workbook()
    ' Load a workbook from a file.
    workbook.LoadDocument("TopTradingPartners.xlsx", DocumentFormat.Xlsx)

    ' Access an active worksheet.
    Dim worksheet As Worksheet = workbook.Worksheets.ActiveWorksheet

    ' Specify thumbnail options.
    Dim thumbnailOptions = New WorksheetThumbnailOptions With {
      .Resolution = 192,
      .Scale = 80,
      .ColumnOffset = 1,
      .RowOffset = 1,
      .BackgroundColor = Color.FromArgb(&HF2, &HF2, &HF2)
    }

    ' Create a thumbnail image.
    If worksheet IsNot Nothing Then
            worksheet.CreateThumbnail("Worksheet_Thumbnail.png", ImageFileFormat.Png, 1600, 900, thumbnailOptions)
    End If
End Using

Tip

You can use the CellRangeExtensions.ExportToImage extension method of a CellRange object to save a cell range as an image. Refer to the following help topic for a code sample: How to: Save a Cell Range as an Image.