Environment Configuration – C#

It is often helpful to have different configurations based on the environment where the application is running. For example, you may wish to configure the scripts policy, override document style applying a custom user stylesheet, or handle any web requests from the application. Aspose.HTML for .NET provides the Configuration class that can be used exactly for these purposes.

Sandboxing

A sandboxing flag set is a set of zero or more of the flags, which are used to restrict the abilities that potentially untrusted resources. The sandbox attribute allows you to set a number of restrictions on the content loaded in the frame, for example, block forms and scripts. This improves the security of the current document, especially when a document is loaded into the frame from an unverified source.

The following example demonstrates how to mark Scripts as an untrusted resource. As a result, Scripts will be disabled during the application execution.

// Prepare HTML code and save it to a file
var code = "<span>Hello, World!!</span> " +
           "<script>document.write('Have a nice day!');</script>";

File.WriteAllText(Path.Combine(OutputDir, "sandboxing.html"), code);

// Create an instance of Configuration
using (var configuration = new Configuration())
{
    // Mark 'scripts' as an untrusted resource
    configuration.Security |= Sandbox.Scripts;

    // Initialize an HTML document with specified configuration
    using (var document = new HTMLDocument(Path.Combine(OutputDir, "sandboxing.html"), configuration))
    {
        // Convert HTML to PDF
        Converter.ConvertHTML(document, new PdfSaveOptions(), Path.Combine(OutputDir, "sandboxing_out.pdf"));
    }
}

Services

All important functional is grouped into separated services for usability purpose and located into Aspose.Html.Services namespace.

User Agent Service

The User Agent Service allows you to specify a custom user stylesheet, a primary character set for the document, language and fonts settings. You can specify your custom style information for a particular document and provide as little or as much environment configuration changes as needed. The IUserAgentService interface describes a user agent environment.

User Style Sheet

The user is able to specify a custom style information for a particular document. This information applies to the document according to the cascading rules and may affect the presentation of the document. The next code snippet shows how to use the UserStyleSheet property:

// Prepare HTML code and save it to a file
var 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 (var configuration = new Configuration())
{
    // Get the IUserAgentService
    var 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 (var 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. In order to parse and display an HTML document correctly, the application must know what character-set (encoding) is used for the document. If the character encoding is not directly specified in the header of the document, Aspose.HTML for .NET uses UTF-8, which is defined as the default for HTML5 specification. However, if you are sure that your HTML document is written using different from UTF-8 encoding, you can specify it manually, as it follows.

// Prepare HTML code and save it to a file
var 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 (var configuration = new Configuration())
{
    // Get the IUserAgentService
    var 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 (var 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"));
    }
}

In the example above, we have used CharSet and UserStyleSheet properties for a setting of ISO-8859-1 encoding and a user style.

Install Font Folder

Aspose.HTML for .NET is a powerful library for working with HTML documents in .NET applications. It provides a wide range of features to enable developers to render HTML documents to various output formats, such as PDF, XPS, DOCX, and images. One of the key features of Aspose.HTML is its ability to work with custom fonts, enabling developers to add their own fonts to the rendering process.

The FontsSettings property is used for configuration of fonts handling. For a situation when you need to use the custom fonts instead of the fonts installed on OS, you can set the path to your custom folder, as it is shown in the following code snippet:

// Prepare HTML code and save it to a file
var 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 (var configuration = new Configuration())
{
    // Get the IUserAgentService
    var 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 (var 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"));
    }
}

To set font folder using Aspose.HTML for .NET library, we use the SetFontsLookupFolder() method of the FontsSettings class. This method allows you to specify the folder where custom fonts are located. By setting the font folder, Aspose.HTML will look for fonts in the specified folder when rendering the HTML document.

The figure illustrates the result of the FontsSettings and UserStyleSheet properties applying (b) to the source “user-agent-fontsetting.html” file (a).

Runtime Service

This service gives you control over the lifetime of the internal processes. For instance, using IRuntimeService you can specify timeouts for JavaScripts. It is important to have such a timeout in case if a script contains an endless loop. The next code snippet demonstrates how to use timeouts.

// Prepare an HTML code and save it to a file
var 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 (var configuration = new Configuration())
{
    // Limit JS execution time to 5 seconds
    var runtimeService = configuration.GetService<IRuntimeService>();
    runtimeService.JavaScriptTimeout = TimeSpan.FromSeconds(5);

    // Initialize an HTML document with specified configuration
    using (var 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"));
    }
}

Network Service

Aspose.HTML for .NET offers the INetworkService that allows you to control all incoming/outcoming traffic and implement your custom message handlers. It can be used for different purposes, such as: create custom caching mechanism, trace/logging request messages, etc.

Message Handlers

The following example demonstrates how to create a custom message handler – LogMessageHandler – to log information about unreachable resources:

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 code snippet demonstrates how to use the LogMessageHandler class created in the previous example to log information about unavailable resources.

// Prepare HTML code and save it to a file
var 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 (var configuration = new Configuration())
{
    // Add the LogMessageHandler to the chain of existing message handlers
    var networkService = configuration.GetService<INetworkService>();

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

    // Initialize an HTML document with specified configuration
    using (var 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 run:

• the created file network-service.html will be converted to PNG. Only one image is in the PNG file;
• the List of ErrorMessages will be printed:

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

You can download the complete examples and data files from GitHub.