Environment Configuration in C#

Use the Configuration class when an HTML workflow needs a controlled processing environment. You can configure sandbox flags, user agent settings, custom stylesheets, character encoding, font lookup folders, JavaScript runtime timeout, and network message handlers before creating an HTMLDocument.

Environment configuration is useful when the same HTML workflow must behave consistently across local machines, servers, Docker images, or restricted runtime environments. In Aspose.HTML for .NET, configuration is created first, services are adjusted through that configuration, and the configured object is passed to the HTMLDocument constructor.

This page is an overview of the main configuration services. For task-specific guides, use the deeper articles linked from each section: Sandboxing for security flags, How to Set Font Folder for rendering with custom fonts, and Message Handlers for advanced network request control.

Choose a Configuration Area

If you need to	Configure this
Disable scripts, images, forms, plugins, or navigation	Sandboxing with Configuration.Security and Sandbox flags.
Apply a user stylesheet to every rendered document	IUserAgentService.UserStyleSheet.
Specify the document encoding when it is not detected correctly	IUserAgentService.CharSet.
Use custom fonts for rendering and conversion	IUserAgentService.FontsSettings.SetFontsLookupFolder().
Limit JavaScript execution time	IRuntimeService.JavaScriptTimeout.
Log, inspect, block, or customize network requests	INetworkService.MessageHandlers.

Sandboxing

Sandboxing controls selected document capabilities through Configuration.Security. Use it when a workflow should treat scripts, images, forms, plugins, navigation, or origin behavior as restricted before the document is loaded.

The dedicated Sandboxing article explains Sandbox flags and includes examples for disabling scripts and image loading. Keep sandbox-related implementation details there; this page treats sandboxing as one part of the broader configuration model.

User Agent Service

The IUserAgentService interface describes user-agent-level settings used while processing HTML. Use it to apply a user stylesheet, set a primary character set, and configure font lookup behavior for rendering.

User Style Sheet

A user stylesheet lets you apply CSS rules through configuration instead of modifying the source HTML. The rules participate in the CSS cascade and can affect rendered output such as PDF, XPS, DOCX, and images.

To apply a user stylesheet in C#:

1. Create a Configuration instance.
2. Get IUserAgentService with configuration.GetService<IUserAgentService>().
3. Assign CSS rules to userAgentService.UserStyleSheet.
4. Create an HTMLDocument with the configuration.
5. Render or convert the document.

// Apply custom CSS via user agent service during HTML processing in C#

// Prepare HTML code and save it to a file
string code = "<h1>User Agent Service </h1>\r\n" +
              "<p>The User Agent Service allows you to specify a custom user stylesheet, a primary character set for the document, language and fonts settings.</p>\r\n";

File.WriteAllText(Path.Combine(OutputDir, "user-agent-stylesheet.html"), code);

// Create an instance of Configuration
using (Configuration configuration = new Configuration())
{
    // Get the IUserAgentService
    IUserAgentService userAgentService = configuration.GetService<IUserAgentService>();

    // Set the custom style parameters for the <h1> and <p> elements
    userAgentService.UserStyleSheet = "h1 { color:#a52a2a;; font-size:2em;}\r\n" +
                                      "p { background-color:GhostWhite; color:SlateGrey; font-size:1.2em; }\r\n";

    // Initialize the HTML document with specified configuration
    using (HTMLDocument document = new HTMLDocument(Path.Combine(OutputDir, "user-agent-stylesheet.html"), configuration))
    {
        // Convert HTML to PDF
        Converter.ConvertHTML(document, new PdfSaveOptions(), Path.Combine(OutputDir, "user-agent-stylesheet_out.pdf"));
    }
}

Character Set

The CharSet property sets the primary character set for a document. If the document does not declare an encoding, Aspose.HTML for .NET uses UTF-8, the default encoding for HTML5. Set CharSet manually only when you know the source HTML uses another encoding and the encoding is not detected from the document itself.

To set the character set in C#:

1. Create a Configuration instance.
2. Get IUserAgentService from the configuration.
3. Set userAgentService.CharSet, for example to ISO-8859-1.
4. Create the HTMLDocument with the configuration.
5. Convert or render the document.

// Set character encoding and custom styles for HTML to PDF conversion in C#

// Prepare HTML code and save it to a file
string code = "<h1>Character Set</h1>\r\n" +
              "<p>The <b>CharSet</b> property sets the primary character-set for a document.</p>\r\n";

File.WriteAllText(Path.Combine(OutputDir, "user-agent-charset.html"), code);

// Create an instance of Configuration
using (Configuration configuration = new Configuration())
{
    // Get the IUserAgentService
    IUserAgentService userAgentService = configuration.GetService<IUserAgentService>();

    // Set the custom style parameters for the <h1> and <p> elements
    userAgentService.UserStyleSheet = "h1 { color:salmon; }\r\n" +
                                      "p { background-color:#f0f0f0; color:DarkCyan; font-size:1.2em; }\r\n";

    // Set ISO-8859-1 encoding to parse the document
    userAgentService.CharSet = "ISO-8859-1";

    // Initialize the HTML document with specified configuration
    using (HTMLDocument document = new HTMLDocument(Path.Combine(OutputDir, "user-agent-charset.html"), configuration))
    {
        // Convert HTML to PDF
        Converter.ConvertHTML(document, new PdfSaveOptions(), Path.Combine(OutputDir, "user-agent-charset_out.pdf"));
    }
}

Install Font Folder

Font configuration matters when HTML rendering depends on fonts that are not installed in the operating system or container image. Use FontsSettings and SetFontsLookupFolder() to point Aspose.HTML to a folder with custom fonts.

To configure a custom font folder in C#:

1. Create a Configuration instance.
2. Get IUserAgentService from the configuration.
3. Call userAgentService.FontsSettings.SetFontsLookupFolder(fontFolder).
4. Create the HTMLDocument with the configuration.
5. Convert or render the document.

// Set font folder for HTML to PDF conversion using C#

// Prepare HTML code and save it to a file
string code = "<h1>FontsSettings property</h1>\r\n" +
              "<p>The FontsSettings property is used for configuration of fonts handling.</p>\r\n";

File.WriteAllText(Path.Combine(OutputDir, "user-agent-fontsetting.html"), code);

// Create an instance of Configuration
using (Configuration configuration = new Configuration())
{
    // Get the IUserAgentService
    IUserAgentService userAgentService = configuration.GetService<IUserAgentService>();

    // Set the custom style parameters for the <h1> and <p> elements
    userAgentService.UserStyleSheet = "h1 { color:#a52a2a; }\r\n" +
                                      "p { color:grey; }\r\n";

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

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

The figure compares rendering before and after applying FontsSettings and UserStyleSheet: (a) the source HTML rendered with default font settings; (b) the result after configuring a custom font folder and user stylesheet.

For a deeper workflow, see How to Set Font Folder.

Runtime Service

The IRuntimeService interface controls runtime behavior for internal processing. A common use case is limiting JavaScript execution time so an endless or long-running script cannot block the workflow indefinitely.

The next example sets JavaScriptTimeout to five seconds before loading an HTML document that contains an endless loop.

To limit JavaScript execution time in C#:

1. Create a Configuration instance.
2. Get IRuntimeService with configuration.GetService<IRuntimeService>().
3. Set runtimeService.JavaScriptTimeout to the required TimeSpan.
4. Create the HTMLDocument with the configuration.
5. Render or convert the document.

// Limit JavaScript execution time for HTML rendering using C#

// Prepare an HTML code and save it to a file
string code = "<h1>Runtime Service</h1>\r\n" +
              "<script> while(true) {} </script>\r\n" +
              "<p>The Runtime Service optimizes your system by helping it start apps and programs faster.</p>\r\n";

File.WriteAllText(Path.Combine(OutputDir, "runtime-service.html"), code);

// Create an instance of Configuration
using (Configuration configuration = new Configuration())
{
    // Limit JS execution time to 5 seconds
    IRuntimeService runtimeService = configuration.GetService<IRuntimeService>();
    runtimeService.JavaScriptTimeout = TimeSpan.FromSeconds(5);

    // Initialize an HTML document with specified configuration
    using (HTMLDocument document = new HTMLDocument(Path.Combine(OutputDir, "runtime-service.html"), configuration))
    {
        // Convert HTML to PNG
        Converter.ConvertHTML(document, new ImageSaveOptions(), Path.Combine(OutputDir, "runtime-service_out.png"));
    }
}

If scripts should not run at all, use Sandboxing with Sandbox.Scripts instead of only setting a timeout.

Network Service

The INetworkService interface lets you control request and response processing through message handlers. Use it when you need request logging, caching, URL filtering, custom schemes, authentication, timeouts, or other network-layer behavior.

For a complete introduction to handler pipelines, see Message Handlers. The example below keeps a compact logging scenario inside this overview page.

Log Unavailable Resources

The first snippet defines a custom LogMessageHandler class that records failed resource requests. The handler checks the response status and stores a message when a requested resource cannot be loaded.

// Сustom network message handler to log HTTP errors during HTML processing

private class LogMessageHandler : MessageHandler
{
    private List<string> errors = new List<string>();

    public List<string> ErrorMessages
    {
        get { return errors; }
    }

    public override void Invoke(INetworkOperationContext context)
    {
        // Check whether response is OK
        if (context.Response.StatusCode != HttpStatusCode.OK)
        {
            // Set error information
            errors.Add(string.Format("File '{0}' Not Found", context.Request.RequestUri));
        }

        // Invoke the next message handler in the chain
        Next(context);
    }
}

The next snippet adds LogMessageHandler to the INetworkService.MessageHandlers collection, loads HTML with several image URLs, converts it to PNG, and prints messages for unavailable resources.

To log unavailable resources in C#:

1. Create a custom message handler by inheriting from MessageHandler.
2. Override Invoke() and inspect context.Response.StatusCode.
3. Get INetworkService from the configuration.
4. Add the handler to networkService.MessageHandlers.
5. Load and process the document with that configuration.
6. Read or print the collected log messages after processing.

// Log network errors during HTML processing using custom message handler in C#

// Prepare HTML code and save it to a file
string code = "<img src=\"https://docs.aspose.com/svg/net/drawing-basics/filters-and-gradients/park.jpg\" >\r\n" +
              "<img src=\"https://docs.aspose.com/html/net/missing1.jpg\" >\r\n" +
              "<img src=\"https://docs.aspose.com/html/net/missing2.jpg\" >\r\n";

File.WriteAllText(Path.Combine(OutputDir, "network-service.html"), code);

// Create an instance of Configuration
using (Configuration configuration = new Configuration())
{
    // Add the LogMessageHandler to the chain of existing message handlers
    INetworkService networkService = configuration.GetService<INetworkService>();

    LogMessageHandler logHandler = new LogMessageHandler();
    networkService.MessageHandlers.Add(logHandler);

    // Initialize an HTML document with specified configuration
    using (HTMLDocument document = new HTMLDocument(Path.Combine(OutputDir, "network-service.html"), configuration))
    {
        //Convert HTML to PNG
        Converter.ConvertHTML(document, new ImageSaveOptions(), Path.Combine(OutputDir, "network-service_out.png"));

        // Print the List of ErrorMessages
        foreach (string errorMessage in logHandler.ErrorMessages)
        {
            Console.WriteLine(errorMessage);
        }
    }
}

After the example runs, network-service.html is converted to PNG. The available image is rendered, and unavailable image URLs are written to the ErrorMessages list:

File 'https://docs.aspose.com/html/net/missing1.jpg' Not Found
File 'https://docs.aspose.com/html/net/missing2.jpg' Not Found

Common Environment Configuration Issues

Problem	Cause	Solution
Configuration changes have no effect	The HTMLDocument was created before the service property or sandbox flag was changed.	Configure services first, then pass the configured Configuration instance to the HTMLDocument constructor.
User stylesheet is ignored	The CSS was assigned after the document was loaded, or the selector does not match document elements.	Set UserStyleSheet before creating the document and verify selectors against the source HTML.
Custom fonts are not used	The font folder path is wrong, the folder does not contain required fonts, or the runtime environment cannot access it.	Use an existing folder with required font files and configure it before rendering. For details, see How to Set Font Folder.
JavaScript runs too long	Runtime timeout is not configured, or scripts should be blocked rather than limited.	Set IRuntimeService.JavaScriptTimeout for time limits, or use Sandboxing to disable scripts.
Remote resources fail to load	Network access, certificates, URLs, or custom handlers block the request.	Inspect requests with INetworkService.MessageHandlers or use dedicated Message Handlers examples.

FAQ

What is Configuration used for in Aspose.HTML for .NET?

Configuration defines the environment used when creating an HTMLDocument. It can control sandbox flags, user agent settings, character encoding, fonts, runtime behavior, and network services.

How do I apply a user stylesheet without changing the source HTML?

Get IUserAgentService from the configuration and assign CSS rules to UserStyleSheet before creating the HTMLDocument. The stylesheet is applied during document processing and rendering.

How do I set a custom character encoding?

Set IUserAgentService.CharSet before loading the document. Use this only when the source HTML does not declare the correct encoding or the encoding cannot be detected reliably.

How do I use custom fonts for HTML rendering?

Configure IUserAgentService.FontsSettings.SetFontsLookupFolder(fontFolder) before rendering or conversion. For a full workflow, see How to Set Font Folder.

When should I use Network Service?

Use INetworkService.MessageHandlers when you need request logging, caching, authentication, timeouts, custom schemes, or URL-level request control. For deeper examples, see Message Handlers.

Can one Configuration combine several services?

Yes. A single Configuration instance can combine user agent settings, runtime timeout, sandbox flags, and network message handlers before it is passed to HTMLDocument.

Related Articles

• Sandboxing – disable scripts, images, forms, plugins, navigation, or other HTML capabilities with sandbox flags.
• How to Set Font Folder – configure custom fonts for HTML rendering and conversion.
• Message Handlers – customize request processing, logging, authentication, custom schemes, and network behavior.
• Network Timeouts – set timeouts for network operations with message handlers.
• Save HTML Document – save HTML output after configured processing.

The complete C# examples and data files are available in the Aspose.HTML for .NET GitHub repository.