Set Custom Font Folder in C#

To use custom fonts during HTML rendering in C#, create a Configuration, get IUserAgentService, call FontsSettings.SetFontsLookupFolder(), then load the HTMLDocument with that configuration and convert it to PDF or image.

Why Custom Fonts Matter

Fonts play an important role in shaping the text’s look, accessibility, aesthetic appeal, and emotional impact. Therefore, choosing the right font can be crucial for achieving specific goals, whether making a text more visually appealing, readable, or recognizable. In certain cases, you might desire to install custom fonts that you have designed, bought, or acquired from an external source.

This article describes how to set a font folder so Aspose.HTML for .NET can use custom fonts when rendering HTML documents to PDF and image formats.

Set a Custom Font Folder in C#

Aspose.HTML for .NET is a powerful library for working with HTML documents. It allows developers to access and manipulate the HTML DOM in C# and other .NET languages. It also provides the ability to set font folders for rendering HTML documents to particular formats.

By default, Aspose.HTML for .NET looks for fonts installed in the system. The FontsSettings class lets you configure where Aspose.HTML looks for fonts when rendering documents.

The C# examples below demonstrate how to set a font folder for rendering an HTML document to PDF and image formats. They use the SetFontsLookupFolder() methods to specify where custom fonts are located. Before you start:

1. Locate the custom font files that you want to use.
2. Create a folder where you will store the custom fonts.
3. Copy the custom fonts to the font folder.

Render HTML to PDF with a Custom Font Folder

When rendering an HTML document to a PDF file, for example, it is important to ensure that the custom fonts used in the HTML document are available to the rendering engine. By default, Aspose.HTML looks for fonts in the system font folder. However, if you are using custom fonts, you will need to call the SetFontsLookupFolder(fontsFolder) method and tell it where to find them.

To set a custom font folder for HTML to PDF conversion:

1. Create a Configuration object.
2. Get IUserAgentService from the configuration by calling GetService().
3. Call SetFontsLookupFolder(fontsFolder) and pass the folder that contains the required font files.
4. Initialize HTMLDocument with the configured Configuration.
5. Call Converter.ConvertHTML() with PdfSaveOptions and save the PDF output.

Here is an example of how to set a custom font folder and render an HTML document to PDF:

// Use custom font folder in HTML to PDF conversion

// Prepare a path to a source HTML file
string documentPath = Path.Combine(DataDir, "file.html");

// Create an instance of Configuration
using Configuration configuration = new Configuration();

// Get the IUserAgentService
IUserAgentService service = configuration.GetService<IUserAgentService>();

// Set a custom font folder path
service.FontsSettings.SetFontsLookupFolder(Path.Combine(DataDir + "fonts"));

// Initialize the HTML document with specified configuration
using (HTMLDocument document = new HTMLDocument(documentPath, configuration))
{
    // Convert HTML to PDF
    Converter.ConvertHTML(document, new PdfSaveOptions(), Path.Combine(OutputDir, "file-fontsetting.pdf"));
}

The configured font folder should contain every custom font required by the HTML document. If the expected font is not available in the configured folder, the rendered PDF may use a fallback font or show text differently from the source design.

Render HTML to Image with a Custom Font Folder

The same configuration approach can be used when converting HTML to PNG, JPG, BMP, GIF, or TIFF. The image example uses SetFontsLookupFolder(fontsFolder, recursive), where the second parameter controls whether nested font folders are included.

To set a custom font folder for HTML to image conversion:

1. Create a Configuration object and get the IUserAgentService.
2. Call SetFontsLookupFolder(fontsFolder, true) when fonts may be stored in nested directories.
3. Initialize HTMLDocument with the configured Configuration.
4. Create image save options if you need a specific image format or rendering setup.
5. Call Converter.ConvertHTML() and save the image output.

Here is an example of how to convert an HTML document to an image format while using a custom font folder:

// Set custom font folder for HTML to PNG conversion in C#

// Prepare a path to a source HTML file
string documentPath = Path.Combine(DataDir, "file.html");

// Prepare a path to save the converted file
string savePath = Path.Combine(OutputDir, "file-output.png");

// Create an instance of the Configuration class
using Configuration configuration = new Configuration();

// Get the IUserAgentService
IUserAgentService userAgentService = configuration.GetService<IUserAgentService>();

// Use the SetFontsLookupFolder() method to set a directory which will act as a new fontsFolder
// Pass "true" as the recursive parameter to use all nested directories
userAgentService.FontsSettings.SetFontsLookupFolder(Path.Combine(DataDir + "font"), true);

// Initialize the HTML document with specified configuration
using (HTMLDocument document = new HTMLDocument(documentPath, configuration))
{
    // Convert HTML to Image
    Converter.ConvertHTML(document, new ImageSaveOptions(), savePath);
}

Thus, by setting the font folder using SetFontsLookupFolder() methods, the Aspose.HTML library will use the custom fonts located in the specified folder to render the HTML document to various output formats, such as PDF or images, ensuring that the documents are displayed as intended with the desired fonts.

Common Font Folder Issues

Issue	Cause	Fix
Custom font is not used in PDF or image output	The font file is not in the folder passed to SetFontsLookupFolder().	Copy the required .ttf or .otf files into the configured font folder and rerun the conversion.
Fonts in subfolders are ignored	The non-recursive overload is used, or the recursive parameter is false.	Use SetFontsLookupFolder(fontsFolder, true) when fonts are organized in nested folders.
Output differs between local machine and server	The available system fonts or custom font folder content differs between environments.	Package the required fonts with the application and configure the same font folder in each environment.

FAQ

Does Aspose.HTML use system fonts by default?

Yes. By default, Aspose.HTML for .NET looks for fonts installed in the system. Use FontsSettings.SetFontsLookupFolder() when your HTML requires fonts stored in a specific application folder.

When should I use the recursive font lookup overload?

Use SetFontsLookupFolder(fontsFolder, true) when the custom font directory contains nested folders. This tells Aspose.HTML to include subfolders in font lookup.

Can the same font folder be used for PDF and image conversion?

Yes. Configure the font folder on Configuration, load the HTMLDocument with that configuration, and use the same document in PDF or image conversion workflows.

Related Articles

• Convert HTML to PDF in C# – render HTML documents to PDF with PdfSaveOptions.
• Convert HTML to PNG in C# – render HTML documents to raster images.
• Resize Document During Conversion – control page size, margins, and output dimensions.
• Aspose.HTML for .NET examples on GitHub – download complete C# examples and data files.