Guias

Introdução
Guias

Engine

Este guia descreve como criar, utilizar e fechar o Engine.

Consulte o guia Arquitetura para obter informações sobre como a arquitetura do DotNetBrowser foi concebida e funciona, bem como sobre os principais componentes que ele fornece.

Criando um engine

Para criar uma nova instância IEngine, utilize os métodos estáticos EngineFactory.Create() ou EngineFactory.Create(EngineOptions). A sobrecarga do método com EngineOptions inicializa e executa o engine Chromium com as opções passadas.

IEngine engine = EngineFactory.Create(engineOptions);

Dim engine As IEngine = EngineFactory.Create(engineOptions)

Dependendo do desempenho do hardware, o processo de inicialização pode demorar vários segundos. Recomendamos que não chame este método na thread da IU da aplicação porque pode congelar toda a aplicação durante algum tempo. Utilize a abordagem descrita no exemplo.

Quando uma nova instância do IEngine é criada, o DotNetBrowser executa as seguintes ações:

  1. Verifica o ambiente e certifica-se de que é um ambiente suportado.
  2. Encontra os binários do Chromium e os extrai para a pasta se necessário.
  3. Executa o processo principal do engine Chromium.
  4. Estabelece a conexão IPC entre o .NET e o processo principal do Chromium.

Opções do engine

Esta seção destaca as principais opções do Engine que você pode personalizar.

Modo de renderização

Esta opção indica a forma como o conteúdo de uma página Web é renderizado. O DotNetBrowser suporta os seguintes modos de renderização:

  • acelerado por hardware
  • fora da tela

Modo acelerado por hardware

O Chromium renderiza o conteúdo utilizando a GPU e apresenta-o diretamente numa superfície. Ver o exemplo de código abaixo:

IEngine engine = EngineFactory.Create(RenderingMode.HardwareAccelerated);

Dim engine As IEngine = EngineFactory.Create(RenderingMode.HardwareAccelerated)

Leia mais sobre o modo de renderização acelerada por hardware, seu desempenho e limitações.

Modo fora da tela

O Chromium renderiza o conteúdo utilizando a GPU e copia os pixéis para a RAM. Veja o exemplo de código abaixo:

IEngine engine = EngineFactory.Create(RenderingMode.OffScreen);

Dim engine As IEngine = EngineFactory.Create(RenderingMode.OffScreen)

Leia mais sobre o modo de renderização fora da tela, o seu desempenho e limitações.

Idioma

Esta opção configura o idioma utilizado nas páginas de erro predefinidas e nas caixas de diálogo da mensagem. Por padrão, o idioma é configurado dinamicamente de acordo com a localidade predefinida da sua aplicação .NET. Se a lista de idiomas suportados não contiver o idioma obtido a partir da localidade da aplicação .NET, o inglês americano é utilizado.

A opção atual permite substituir o comportamento predefinido e configurar o engine Chromium com o idioma fornecido. Veja o exemplo de código abaixo:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    Language = DotNetBrowser.Ui.Language.German
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .Language = DotNetBrowser.Ui.Language.German
}.Build())

No exemplo de código acima, configuramos o IEngine com o idioma alemão. Se o DotNetBrowser não conseguir carregar uma página Web, a página de erro em alemão é apresentada:

Página de erro

Pasta de dados do usuário

Representa um caminho absoluto para a pasta que contém os perfis e os seus dados, tais como cache, cookies, histórico, cache GPU, armazenamento local, ligações visitadas, dados Web, pastas de dicionário de verificação ortográfica, etc. Veja o exemplo de código abaixo:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    UserDataDirectory = @"C:\Users\Me\DotNetBrowser"
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .UserDataDirectory = "C:\Users\Me\DotNetBrowser"
}.Build())

O mesmo diretório de dados do utilizador não pode ser utilizado simultaneamente por várias instâncias do IEngine executadas numa única ou em diferentes aplicações .NET. A criação do IEngine falha se a pasta já estiver sendo utilizada por outro IEngine.

Se não fornecer o caminho da pasta de dados do usuário, o DotNetBrowser cria e utiliza uma pasta temporária do utilizador.

Incógnito

Esta opção indica se o modo incógnito para o perfil predefinido está ativado. Neste modo, os dados do usuário, como o histórico de navegação, os cookies, os dados do site e as informações introduzidas nos formulários das páginas Web, são armazenados na memória. Ela será libertada assim que eliminar o Profile ou eliminar o engine IEngine.

Por predefinição, o modo de navegação anônima está desativado.

O exemplo seguinte demonstra como ativar o modo de navegação anônima:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    IncognitoEnabled = true
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .IncognitoEnabled = true
}.Build())

Pedido de interceção por esquema URI

A opção Schemes pode ser utilizada para configurar a interceção de pedidos de URL por esquema. Eis como configurá-la para interceptar e tratar todos os pedidos para os esquemas de URI personalizados:

Handler<InterceptRequestParameters, InterceptRequestResponse> handler =
    new Handler<InterceptRequestParameters, InterceptRequestResponse>(p =>
    {
        UrlRequestJobOptions options = new UrlRequestJobOptions
        {
            Headers = new List<HttpHeader>
            {
                new HttpHeader("Content-Type", "text/html", "charset=utf-8")
            }
        };

        UrlRequestJob job = p.Network.CreateUrlRequestJob(p.UrlRequest, options);

        Task.Run(() =>
        {
            // O processamento do pedido é efetuado numa thread de trabalho
            // para evitar o congelamento da página Web.
            job.Write(Encoding.UTF8.GetBytes("Hello world!"));
            job.Complete();
        });

        return InterceptRequestResponse.Intercept(job);
    });

EngineOptions engineOptions = new EngineOptions.Builder
{
    Schemes = 
    {
        { Scheme.Create("myscheme"), handler }
    }
}.Build();

using (IEngine engine = EngineFactory.Create(engineOptions))
{
    using (IBrowser browser = engine.CreateBrowser())
    {
        NavigationResult result =
            browser.Navigation.LoadUrl("myscheme://test1").Result;

        // Se o handler de esquema não fosse definido, o LoadResult seria 
        // LoadResult.Stopped.
        // No entanto, com o handler de esquema, a página web é carregada e
        // o resultado é LoadResult.Completed.
        Console.WriteLine($"Load result: {result.LoadResult}");
        Console.WriteLine($"HTML: {browser.MainFrame.Html}");
    }
}

Dim interceptRequestHandler =
        New Handler(Of InterceptRequestParameters, InterceptRequestResponse)(
            Function(p)
                Dim options = New UrlRequestJobOptions With {
                        .Headers = New List(Of HttpHeader) From {
                        New HttpHeader("Content-Type", "text/html",
                                       "charset=utf-8")
                        }
                        }

                Dim job As UrlRequestJob =
                        p.Network.CreateUrlRequestJob(p.UrlRequest, options)

                Task.Run(Sub()
                             ' O processamento do pedido é efetuado numa thread de trabalho
                             ' para evitar o congelamento da página Web.
                             job.Write(Encoding.UTF8.GetBytes("Olá Mundo!"))
                             job.Complete()
                         End Sub)

                Return InterceptRequestResponse.Intercept(job)
            End Function)


Dim engineOptionsBuilder = new EngineOptions.Builder
With engineOptionsBuilder
    .Schemes.Add(Scheme.Create("myscheme"), interceptRequestHandler)
End With

Dim engineOptions = engineOptionsBuilder.Build()

Using engine As IEngine = EngineFactory.Create(engineOptions)

    Using browser As IBrowser = engine.CreateBrowser()
        Dim result As NavigationResult =
                browser.Navigation.LoadUrl("myscheme://test1").Result
        ' Se o handler de esquema não estivesse definido, o LoadResult seria 
        ' LoadResult.Stopped.
        No entanto, com o handler de esquemas, a página Web é carregada e
        ' o resultado é LoadResult.Completed.
        Console.WriteLine($"Carregar resultado: {result.LoadResult.ToString()}")
        Console.WriteLine($"HTML: {browser.MainFrame.Html}")
    End Using
End Using

Vá ao nosso repositório para obter o exemplo completo: C#, VB.NET.

A mesma abordagem pode ser utilizada para interceptar e tratar todos os pedidos HTTPS.

Nem todos os esquemas podem ser interceptados. Por exemplo, não é possível interceptar esquemas como chrome, data, ou chrome-extensions. A tentativa de os interceptar pode levar a um comportamento inesperado ou a uma falha no Chromium.

Além disso, alguns esquemas são tratados como esquemas locais, por exemplo, file. Eles não podem ser interceptados porque não se trata de um pedido de rede.

Se o esquema especificado não puder ser interceptado, a exceção correspondente será lançada pelo construtor EngineOptions. Por exemplo: “O esquema “file” não pode ser interceptado.”

Agente do usuário

Com esta opção, você pode configurar a string padrão do agente do usuário. Veja o exemplo de código abaixo:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    UserAgent = "<user-agent>"
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .UserAgent = "<user-agent>"
}.Build())

Você pode fazer o override a string padrão do agente do usuário em cada instância do IBrowser.

Porta de depuração remota

Esta opção permite ativar a depuração remota das Ferramentas de desenvolvimento do Chrome (ou DevTools). O exemplo seguinte demonstra como utilizar esta funcionalidade:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    ChromiumSwitches = { "--remote-allow-origins=http://localhost:9222" },
    RemoteDebuggingPort = 9222
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .ChromiumSwitches = { "--remote-allow-origins=http://localhost:9222" },
    .RemoteDebuggingPort = 9222
}.Build())

Desde o Chromium 111, é necessário especificar a opção remote-allow-origins para permitir conexões de sockets web de origem especificada. Mais informações no Problema 1422444.

Agora você pode carregar o URL de depuração remota em uma instância do IBrowser para abrir a página DevTools e inspecionar HTML, depurar JavaScript e outros. Veja um exemplo abaixo:

Porta de depuração remota

Não abra o URL de depuração remota em outras aplicações do navegador Web, como o Mozilla Firefox, o Microsoft Internet Explorer, o Safari, o Opera e outros, pois pode resultar numa falha nativa do servidor Web Chromium DevTools.

O recurso de depuração remota é compatível apenas com a versão do Chromium usada pela biblioteca DotNetBrowser. Por exemplo, se utilizar o DotNetBrowser 2.26.2 baseado no Chromium 123.0.6312.124, você pode abrir o URL de depuração remota apenas no mesmo Chromium/Google Chrome. Se você utilizar uma versão anterior do DotNetBrowser, tem de baixar a compilação Chromium correspondente.

Recomendamos o carregamento do URL de depuração remota numa instância do IBrowser em vez do Google Chrome.

Desativar o menu tátil

O toque longo em dispositivos táteis do Windows 10 pode mostrar o seguinte menu tátil:

Menu tátil

O exemplo de código abaixo demonstra como desativar este menu tátil:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    TouchMenuDisabled = true
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .TouchMenuDisabled = true
}.Build())

Desativar o tráfego do Google

Esta opção desativa o tráfego desnecessário para serviços do Chromium como o Google Cloud Messaging, Translate Ranker, Extensions Updater, Safe Browsing, etc.

Veja o exemplo de código abaixo:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    GoogleTrafficDisabled = true
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .GoogleTrafficDisabled = true
}.Build())

Pasta de binários do Chromium

Utilize esta opção para definir um caminho absoluto ou relativo para a pasta onde os binários do Chromium estão localizados ou para onde devem ser extraídos. Veja o exemplo de código abaixo:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    ChromiumDirectory = @"C:\Users\Me\.DotNetBrowser\chromium"
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .ChromiumDirectory = @"C:\Users\Me\.DotNetBrowser\chromium"
}.Build())

Para obter detalhes, consulte a seção Localização dos Binários do Chromium.

Reprodução automática de vídeos

Para ativar a reprodução automática de conteúdos de vídeo nas páginas Web, utilize a opção abaixo:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    AutoplayEnabled = true
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .AutoplayEnabled = true
}.Build())

Switches do Chromium

Utilize esta opção para definir os switches do Chromium passados para o processo principal do Chromium. Veja o exemplo de código abaixo:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    ChromiumSwitches = { "--<switch-name>", "--<switch-name>=<switch-value>" }
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .ChromiumSwitches = { "--<switch-name>", "--<switch-name>=<switch-value>" }
}.Build())

Nem todas as opções do Chromium são suportadas pelo DotNetBrowser, então não há garantia de que as opções passadas funcionem e não causem quaisquer erros. Recomendamos a configuração do Chromium através das [Opções do Engine] (/pt/docs/guides/gs/engine.html#opções-do-engine) em vez de interruptores.

APIs do Google

Algumas funcionalidades do Chromium, como a Geolocalização, a Ortografia, a Fala e outras, utilizam APIs da Google. Para acessar essas APIs, é necessária uma chave de API, um ID de cliente OAuth 2.0 e uma senha de cliente. Para adquirir a chave da API, siga estas instruções.

Para fornecer a chave da API, o ID do cliente e a senha do cliente, utilize o seguinte exemplo de código:

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    GoogleApiKey = "<api-key>",
    GoogleDefaultClientId = "<client-id>",
    GoogleDefaultClientSecret = "<client-secret>"
}.Build());

Dim engine As IEngine = EngineFactory.Create(New EngineOptions.Builder With 
{
    .GoogleApiKey = "<api-key>",
    .GoogleDefaultClientId = "<client-id>",
    .GoogleDefaultClientSecret = "<client-secret>"
}.Build())

A configuração de chaves API é opcional. No entanto, se isto não for feito, algumas APIs que utilizam os serviços Google não funcionam.

Geolocalização

A geolocalização é uma das funcionalidades do Chromium que utiliza a API do Google. É necessário ativar Google Maps Geolocation API e billing, caso contrário, a Geolocation API não funciona. Depois de ativar a API de geolocalização e a faturação do Google Maps, você pode fornecer as chaves ao engine Chromium do DotNetBrowser.

Para ativar a geolocalização no DotNetBrowser, conceda uma permissão específica.

Reconhecimento de voz

O reconhecimento de voz é uma das funcionalidades do Chromium que utiliza a API do Google. É necessário ativar Speech API e billing, caso contrário o reconhecimento de voz não funciona.

Depois de ativar a Speech API e a faturação, pode fornecer as chaves ao engine Chromium do DotNetBrowser.

Eliminação do engine

A instância IEngine atribui memória e recursos do sistema que têm de ser libertados. Quando o IEngine já não for necessário, deve ser eliminado através do método IEngine.Dispose() para encerrar o processo nativo do Chromium e libertar toda a memória atribuída e os recursos do sistema. Veja o exemplo abaixo:

IEngine engine = EngineFactory.Create();
// ...
engine.Dispose();

Dim engine As IEngine = EngineFactory.Create()
' ...
engine.Dispose()

Qualquer tentativa de utilizar uma IEngine já descartada levará à ObjectDisposedException.

Para verificar se o IEngine foi descartado, utilize a propriedade IsDisposed apresentada no exemplo de código abaixo:

bool disposed = engine.IsDisposed;

Dim disposed As Boolean = engine.IsDisposed

Eventos do engine

Engine descartado

Para receber notificações quando o IEngine for eliminado, utilize o evento Disposed apresentado no exemplo de código abaixo:

engine.Disposed += (s, e) => {};

AddHandler engine.Disposed, Sub(s, e)
End Sub

Engine falhado

Para receber notificações quando o IEngine falha inesperadamente devido a um erro no engine Chromium, utilize a abordagem apresentada no exemplo de código abaixo:

engine.Disposed += (s, e) => 
{
    long exitCode = e.ExitCode;
    // O engine foi desativado se este código de saída for diferente de zero.
});

AddHandler engine.Disposed, Sub(s, e)
    Dim exitCode As Long = e.ExitCode
    ' O engine falhou se este código de saída for diferente de zero.
End Sub)
Go Top