Skip to content

Graphic Engine

Jahav edited this page Oct 25, 2022 · 14 revisions

Graphic Engine is an pluggable component (since 0.97.0) behind IXLGraphicEngine interface that is responsible for working with image formats and fonts. Both image reading and rendered size measurement is a non-trivial problem that is out of scope of ClosedXML.

A default graphic engine ClosedXML.Graphic.DefaultGraphicEngine.Instance) uses "Microsoft Sans Serif" as a fallback font, if workbook tries to render something a missing font. The font is unlikely to be found on non-Windows systems. You might need to create an engine with a font that can be found in the SystemFonts collection (see source) from SixLabors.Fonts library.

// A line needed to be used in non-windows environment before instantiating a workbook.
// On linux, we can't rely on installed fonts, we must specify the fallback font that is actually present.
LoadOptions.DefaultGraphicsEngine = new DefaultGraphicEngine("Tahoma"); // If there is a Tahoma font installed

If the program doesn't use font sizes (AdjustToContent) or contain any pictures, it is possible to omit configuration on linux.

How to plug-in a different graphic engine

You can keep the default engine (no need to configure anything and ClosedXML should just work) or you can specify a different one.

You can specify a different engine globally or individually for each workbook. Global level is done by through a static LoadOptions.DefaultGraphicEngine property

// On Windows
LoadOptions.DefaultGraphicEngine = new SomeGraphicEngine();

// All workbooks created after setting of the engine will use the specified engine.
using var workbook = new XLWorkbook();

If you need to specify an engine on per-workbook basis, use the LoadOptions.GraphicEngine property

// Only workbooks created with the options will use the engine
var loadOptions = new LoadOptions { GraphicEngine = new SomeGraphicEngine() };
using var workbook = new XLWorkbook(loadOptions);

Workbook will use the best engine in the following order:

  • LoadOptions.GraphicEngine - if user specified a specific engine just for the workbook, use that.
  • LoadOptions.DefaultGraphicsEngine - is user specified default engine for all new workbooks, use that.
  • DefaultGraphicEngine.Instance - a graphic engine that uses SixLabors.Fonts library and a custom picture parsing

How to use in Blazor

- Draft of documentation for unreleased version 0.97.1  

Client-side Blazor can't use filesystem and the default instance isn't very useful for them, because it loads system fonts from the filesystem. In a situation where filesystem is not available, it is possible to use a constructor of DefaultGraphicEngine that accepts a stream containing a fallback font.

using Stream fallbackFontStream = Assembly.GetManifestResourceStream("SomeEmbeddedFont.ttf");
LoadOptions.DefaultGraphicEngine = new DefaultGraphicEngine(fallbackFontStream);

Stream must be seekable, so unfortunately it is no possible to load font directly from S3 or other http place without an intermediate stream.

There is also a possibility to load some additional fonts through streams, not just fallback one. That can be done by passing an extra streams to the constructor.

using Stream fallbackFontStream = Assembly.GetManifestResourceStream("SomeEmbeddedFont.ttf");
using Stream calibriFont = /* a way to get stream for a font */;
using Stream arialFont = /* a way to get stream for a font */;
LoadOptions.DefaultGraphicEngine = new DefaultGraphicEngine(fallbackFontStream, calibriFont, arialFont);

Additional fonts are used in lieu of fallback font, if the cell contains one of the passed fonts.

FAQ

Examples

Real world scenarios

Time Savers

Performance and Memory

Misc

Inserting Data/Tables

Styles

Ranges

Rows

Columns

Page Setup (Print Options)

AutoFilters

Comments

Dev docs

Clone this wiki locally