Iyulab.ClosedXML.Report

ClosedXML.Report.XLCustom

Based on ClosedXML.Report
This extension maintains full compatibility with the original library while adding enhanced expression handling capabilities.

What's New

ClosedXML.Report.XLCustom extends the original library with:

• Format expressions: {{Value:F2}}, {{Date:yyyy-MM-dd}}
• Function expressions: {{Value|bold}}, {{ImageUrl|image(150)}}
• Custom function registration
• Built-in functions for styling and formatting

Installation

Install-Package Iyulab.ClosedXML.Report

Requirements

Images are decoded and SVG sources are rasterised through SkiaSharp. The native binaries for all three operating systems ship with this package, so no extra platform package is needed.

Linux containers: the native library links against fontconfig, which slim runtime images (mcr.microsoft.com/dotnet/aspnet, alpine, …) do not install. Add it to your image:

RUN apt-get update && apt-get install -y --no-install-recommends libfontconfig1 \
    && rm -rf /var/lib/apt/lists/*

On Alpine the package is fontconfig. Without it, image and SVG handling fails to load the native library. Most full distributions already have it.

Upgrading from 0.2.x? See CHANGELOG.md. Support for .NET 6.0 and .NET 7.0 was dropped in 0.3.0; both reached end of support in 2024. Stay on 0.2.13 if you still need them.

Quick Start

var template = new XLCustomTemplate("template.xlsx");
template.RegisterBuiltIns(); // Add built-in functions

// Standard ClosedXML.Report usage
template.AddVariable("Title", "Sales Report");
template.AddVariable("Products", productList);

// Custom function registration
template.RegisterFunction("highlight", (cell, value, parameters) => {
    cell.SetValue(value);
    cell.Style.Fill.BackgroundColor = XLColor.Yellow;
});

template.Generate();
template.SaveAs("result.xlsx");

Expression Syntax

Standard Variables (Original ClosedXML.Report)

{{VariableName}}
{{Object.Property}}

Format Expressions (New)

{{Price:C}}           // Currency format
{{Date:yyyy-MM-dd}}   // Date format
{{Value:F2}}          // 2 decimal places

Function Expressions (New)

{{Text|bold}}                    // Make bold
{{Text|color(Red)}}             // Set color
{{ImagePath|image(100,100)}}    // Insert image
{{Url|link(Click here)}}        // Create hyperlink

Built-in Functions

Register with template.RegisterBuiltIns():

Images

The image function accepts a local path or an http/https URL. The picture is scaled to fit its cell while preserving the source aspect ratio, and centred within it.

SVG sources are rasterised to PNG before being placed, since a workbook cannot embed SVG directly. This applies to both local .svg files and downloaded ones. Any temporary file created along the way is removed once the picture has been placed; paths you supply are never deleted.

Built-in Global Variables

Automatically available:

• {{Today:d}} - Current date
• {{Year}} - Current year
• {{MachineName}} - Computer name
• {{UserName}} - User name