Конфигурация среды – Environment Configuration C#

Часто полезно иметь разные конфигурации в зависимости от среды, в которой выполняется приложение. Например, вы можете настроить политику сценариев, переопределить стиль документа, применяя пользовательскую таблицу стилей, или обработать любые веб-запросы из приложения. Aspose.HTML предоставляет класс Configuration, который можно использовать именно для этих целей.

Песочница – Sandbox

Набор «sandboxing flag» – это набор из нуля или более флагов, которые используются для ограничения возможностей потенциально ненадежных ресурсов. Атрибут песочницы позволяет установить ряд ограничений на загружаемый во фрейм контент, например, блокировать формы и скрипты. Это повышает безопасность текущего документа, особенно когда документ загружается во фрейм из непроверенного источника.

В следующем примере показано, как пометить Scripts как ненадежный ресурс. В результате Scripts будут отключены во время выполнения приложения.

// Enable sandboxing to restrict script execution when loading HTML

// Prepare HTML code and save it to a file
string 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 (Configuration configuration = new Configuration())
{
    // Mark 'scripts' as an untrusted resource
    configuration.Security |= Sandbox.Scripts;

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

Весь важный функционал сгруппирован в отдельные сервисы для удобства использования и расположен в пространстве имен Aspose.Html.Services.

Служба пользовательского агента – User Agent Service

User Agent Service позволяет указать настраиваемую таблицу стилей пользователя, основной набор символов для документа, настройки языка и шрифтов. Вы можете указать свою пользовательскую информацию о стиле для конкретного документа и внести столько изменений конфигурации среды, сколько необходимо. Интерфейс IUserAgentService описывает среду пользовательского агента.

Пользовательская таблица стилей – User Style Sheet

Пользователь может указать информацию пользовательского стиля для конкретного документа. Эта информация относится к документу в соответствии с cascading rules и может повлиять на представление документа. Следующий фрагмент кода показывает, как использовать свойство UserStyleSheet:

// 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"));
    }
}

Вы можете скачать полные примеры и файлы данных с GitHub..

Набор символов – Character Set

Свойство CharSet устанавливает первичный набор символов для документа. Чтобы правильно анализировать и отображать HTML-документ, приложение должно знать, какой набор символов (кодировка) используется для документа. Если кодировка символов не указана напрямую в заголовке документа, Aspose.HTML использует UTF-8, которая определена как кодировка по умолчанию для спецификации HTML5. Однако, если вы уверены, что ваш HTML-документ написан с использованием кодировки, отличной от UTF-8, вы можете указать ее вручную, как показано ниже.

// 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"));
    }
}

В приведенном выше примере мы использовали свойства CharSet и UserStyleSheet для настройки кодировки ISO-8859-1 и пользовательского стиля.

Установить папку со шрифтами

Aspose.HTML – это мощная библиотека для работы с документами HTML в приложениях .NET. Он предоставляет широкий спектр функций, позволяющих разработчикам преобразовывать HTML-документы в различные выходные форматы, такие как PDF, XPS, DOCX и изображения. Одной из ключевых особенностей Aspose.HTML является его способность работать с пользовательскими шрифтами, что позволяет разработчикам добавлять свои собственные шрифты в процесс рендеринга. Свойство FontsSettings используется для настройки работы со шрифтами. Для ситуации, когда вам нужно использовать пользовательские шрифты вместо шрифтов, установленных в ОС, вы можете указать путь к своей пользовательской папке, как показано в следующем фрагменте кода:

// 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"));
    }
}

Чтобы установить папку шрифта с помощью библиотеки Aspose.HTML for .NET, мы используем метод SetFontsLookupFolder() класса FontsSettings. Этот метод позволяет указать папку, в которой находятся пользовательские шрифты. Установив папку шрифтов, Aspose.HTML будет искать шрифты в указанной папке при рендеринге HTML-документа.

На рисунке показан результат применения свойств FontsSettings и UserStyleSheet (b) к исходному файлу «user-agent-fontsetting.html» (a).

Служба выполнения – Runtime Service

Эта служба дает вам контроль над временем жизни внутренних процессов. Например, с помощью IRuntimeService вы можете указать время ожидания для JavaScript. Важно иметь такой таймаут на случай, если скрипт содержит бесконечный цикл. Следующий фрагмент кода демонстрирует, как использовать тайм-ауты.

// 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"));
    }
}

Сетевая служба – Network Service

Aspose.HTML for .NET предлагает INetworkService, который позволяет вам контролировать весь входящий/исходящий трафик и реализовывать свои собственные обработчики сообщений. Его можно использовать для различных целей, таких как: создание собственного механизма кэширования, трассировка/логирование сообщений запроса и т. д.

Обработчики сообщений – Message Handlers

В следующем примере показано, как создать собственный обработчик сообщений – LogMessageHandler – для регистрации сведений о недоступных ресурсах:

// С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);
    }
}

В следующем фрагменте кода показано, как использовать класс LogMessageHandler, созданные в примере выше, для регистрации информации о недоступных ресурсах.

// 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);
        }
    }
}

После запуска примера:

• созданный файл network-service.html будет конвертирован в PNG. В файле PNG находится только одно изображение;
• будет распечатан список сообщений об ошибках:

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

Вы можете скачать полные примеры и файлы данных с GitHub.