Extensões do Chrome

Esta página descreve como trabalhar com extensões do Chrome.

A funcionalidade descrita neste artigo está disponível no DotNetBrowser 3.0.0-eap.2 ou superior.

O DotNetBrowser fornece a API de extensões que lhe permite instalar, atualizar e desinstalar extensões do Chrome. As extensões funcionam numa base por perfil e não são compartilhadas com outros perfis. Para acessar as extensões de um perfil específico, utilize a seguinte abordagem:

IExtensions extensions = profile.Extensions();

Se você excluir o perfil, todas as extensões instaladas para este perfil também serão excluídas.

Instalação de extensões

Você pode instalar extensões do Chrome manualmente a partir da Chrome Web Store ou de forma programática a partir de arquivos CRX.

Recomendamos que você instale extensões a partir de arquivos CRX se confiar na fonte da extensão. Em comparação com a instalação de extensões a partir da Chrome Web Store esta lhe oferece as seguintes vantagens:

1. O usuário controla a versão da extensão que instala. Você pode testar a extensão com uma versão específica do DotNetBrowser e certificar-se de que funciona como esperado com a compilação do Chromium que o DotNetBrowser utiliza. Se você instalar a extensão a partir da Chrome Web Store, você instala a versão mais recente da extensão que pode não ser compatível com a versão do DotNetBrowser que utiliza.
2. Você pode implementar a extensão com a sua aplicação e instalá-la automaticamente. Por isso, não é necessário pedir aos usuários que instalem a extensão manualmente a partir da Chrome Web Store.
3. Você pode instalar extensões que não estão disponíveis na Chrome Web Store. Se você desenvolver uma extensão que gostaria de utilizar no DotNetBrowser e não pretender publicá-la na Chrome Web Store, você pode empacotá-la num arquivo CRX e utilizá-la.

Para instalar uma extensão a partir de um arquivo CRX, utilize a seguinte abordagem:

string crxPath = Path.GetFullPath("path/to/extension.crx");
IExtension extension = await extensions.Install(crx);

O método devolve uma instância da extensão instalada. Todas as permissões necessárias para a extensão são concedidas automaticamente.

Importante: Tenha muito cuidado com as extensões que você está instalando. Na Chrome Web Store, o arquivo CRX deve ter uma prova de editor, que é obtida quando da publicação da extensão. No DotNetBrowser, permitimos que os usuários instalem as extensões sem prova do editor, por isso, tenha cuidado com os recursos que utiliza para obter arquivos CRX.

Por padrão, a instalação de extensões da Chrome Web Store está desativada por motivos de segurança. Se você pretender permitir que os usuários instalem extensões da Chrome Web Store, você precisa permitir a instalação utilizando a seguinte abordagem:

extensions.InstallExtensionHandler =
    new Handler<InstallExtensionParameters, InstallExtensionResponse>(p => 
        InstallExtensionResponse.Install);

Sempre que o usuário clicar no botão “Adicionar ao Chrome” na página da Chrome Web Store, o InstallExtensionHandler será invocado. Você pode obter informações sobre a extensão que o usuário pretende instalar a partir do objeto InstallExtensionParameterse decidir se permite ou não a instalação:

extensions.InstallExtensionHandler =
    new Handler<InstallExtensionParameters, InstallExtensionResponse>(p => 
    {
        string name = p.ExtensionName;
        string version = p.ExtensionVersion;
        if (name.Equals("uBlock Origin") && version.Equals("1.35.2")) 
        {
            return InstallExtensionResponse.Install;
        } 
        else 
        {
            return InstallExtensionResponse.Cancel;
        }
    });

Para ser notificado quando a extensão for instalada, utilize o evento ExtensionInstalled:

extensions.ExtensionInstalled += (s, e) => 
{
    IExtension installedExtension = e.Extension;
});

Atualizar extensões

Se você instalar uma extensão a partir de um arquivo CRX e pretender atualizá-la com uma nova versão, basta instalá-la a partir de um novo arquivo CRX:

string updatedCrxPath = Path.GetFullPath("path/to/updated_extension.crx");
IExtension extension = await extensions.Install(updatedCrxPath);

Não é necessário excluir a versão anterior da extensão. O DotNetBrowser atualizará automaticamente a extensão para a versão mais recente.

Importante: Quando estiver instalando uma extensão sem prova de editor, certifique-se de que utiliza a mesma chave privada (arquivo .pem) para o empacotamento. Quando uma chave privada diferente é utilizada ou não é utilizada de nenhum modo, a extensão é considerada nova e é instalada novamente sem atualização.

Se você instalar uma extensão a partir da Chrome Web Store, você não pode atualizá-la programaticamente. O usuário deve atualizar a extensão manualmente a partir da página da extensão na Chrome Web Store.

Para ser notificado quando a extensão for atualizada, utilize o evento ExtensionUpdated:

extensions.ExtensionUpdated += (s, e) => 
{
    IExtension updatedExtension = e.Extension;
});

Desinstalação de extensões

Você pode desinstalar programaticamente a extensão que instalou a partir de um arquivo CRX ou da Chrome Web Store:

IExtension extension = 
    extensions.All.FirstOrDefault(ex => ex.Name.Equals("uBlock Origin"));
await extension.Uninstall();

Se a extensão foi instalada manualmente a partir da Chrome Web Store, o usuário poderá querer desinstalá-la também manualmente. Por padrão, a desinstalação de extensões da Chrome Web Store está desativada por motivos de segurança. Se você desejar permitir que os usuários desinstalem extensões da Chrome Web Store ou da página chrome://extensions, você precisa permitir a desinstalação:

extensions.UninstallExtensionHandler =
    new Handler<UninstallExtensionParameters, UninstallExtensionResponse>(p => 
        UninstallExtensionResponse.Uninstall);

Para ser notificado quando a extensão for desinstalada, utilize o evento ExtensionUninstalled:

extensions.ExtensionUninstalled += (s, e) => 
{
    string extensionId = e.ExtensionId;
});

Uma tentativa de trabalhar com uma extensão desinstalada resultará numa ObjectDisposedException.

Ação de extensão

As extensões do Chrome podem fornecer funcionalidades que só estão disponíveis no “pop-up de ação da extensão”. Esta é uma caixa de diálogo que é apresentada quando se clica no ícone da extensão na barra de ferramentas do Chrome. Embora o DotNetBrowser não apresente a barra de ferramentas do Chrome. Em vez disso, ele fornece uma API para interagir com o pop-up da ação de extensão.

Para simular o clique no ícone da extensão (ação de extensão) na barra de ferramentas do Chrome para uma aba específica, execute o seguinte código:

extension.GetAction(browser)?.Click();

Uma extensão, e não o Chromium, é responsável por escolher um navegador para interagir. Portanto, a ação de extensão pode não ser executada no browser para o qual foi obtida.

Se você deseja apresentar o ícone da extensão na sua aplicação, você pode acessar as propriedades da ação de extensão e subscrever as notificações de atualização da ação:

IExtensionAction action = extension.GetAction(browser);

if (action != null) 
{
    // Obter as propriedades da ação.
    Bitmap icon = action.Icon;
    string badge = action.Badge;
    string tooltip = action.Tooltip;
    bool enabled = action.IsEnabled;

    // Obter notificações quando a ação de extensão é atualizada.
    action.Updated += (s, e) => 
    {
        IExtensionAction updatedAction = e.ExtensionAction;
    });
});

Pop-ups de ações de extensão

Quando se cria uma instância BrowserView, esta registra as implementações padrões da chamada de retorno OpenExtensionActionPopupHandler que exibirá o pop-up da ação de extensão quando o programa simula o clique no ícone da ação de extensão.

Se você deseja apresentar um pop-up de ação de extensão personalizado, registre a sua própria implementação da OpenExtensionActionPopupHandler:

Browser.OpenExtensionActionPopupHandler = 
    new Handler<OpenExtensionActionPopupParameters>(p =>
    {
        IBrowser popupBrowser = p.PopupBrowser;
    });

Pop-ups de extensão

Algumas extensões podem querer abrir janelas pop-up para exibir um site ou outro conteúdo. Por padrão, o DotNetBrowser bloqueia esses pop-ups. Para permitir que a extensão exiba pop-ups, registre a sua própria implementação das seguintes chamadas de retorno:

extension.OpenExtensionPopupHandler = 
    new Handler<OpenExtensionPopupParameters>(p =>
    {
        IBrowser popupBrowser = p.PopupBrowser;
    });

Ou utilize a implementação padrão:

extension.OpenExtensionPopupHandler = new DefaultOpenExtensionPopupHandler(browserView);

Tenha em atenção que “pop-ups de extensão” e “pop-ups de ação de extensão” são coisas diferentes.

Peculiaridades e limitações

Desenvolvemos a API de extensão com o objetivo de se comportar, tanto quanto possível, como o Chromium. Mas como o DotNetBrowser é um navegador incorporado, não podemos garantir o mesmo comportamento para todos os casos. Assim, existem particularidades e limitações que você deve levar em consideração ao trabalhar com extensões.

1. Todas as abas são abertas como novas janelas.
2. O chrome.tabs.query nunca considera os pop-ups de ações de extensão.
3. As janelas do pop-up da ação de extensão são redimensionáveis automaticamente. O tamanho é regulado pela ação de extensão.
4. Quando o DotNetBrowser não encontra o manifesto para mensagens nativas (chrome.runtime.connectNative) no diretório de dados do usuário ou nos dados da aplicação Chromium, ele verifica nos dados da aplicação Chrome.

Existem algumas limitações relacionadas com as abas, janelas e outros elementos da IU do Chromium. O windows.Window é mapeado para uma janela nativa associada ao navegador, e não para a janela .NET na qual está incorporado (se houver). Assim, métodos e propriedades do objeto windows.Window, como Window.width, Window.height, Window.focused, etc., são vinculados a essa janela nativa.

APIs de extensões não suportadas

Abaixo está a lista de APIs de extensão do Chromium que não são suportadas no DotNetBrowser:

• chrome.tabs.discard
• chrome.tabs.remove
• chrome.tabs.duplicate
• chrome.windows.remove
• chrome.windows.update
• chrome.window.create com mais de um URL nos parâmetros
• chrome.sessions.restore
• chrome.desktopCapture.chooseDesktopMedia.

Se uma extensão chamar um método não suportado que devolva um Promise, será rejeitada com um erro. Se um método aceita um retorno de chamada, a propriedade chrome.runtime.lastError será definida como um erro.

Baixe o CRX da Chrome Web Store

Se você deseja baixar um arquivo CRX de uma extensão disponível na Chrome Web Store, pode registrar a chamada de retorno InstallExtensionCallback, na qual você pode obter um caminho absoluto para o arquivo CRX da extensão que está prestes a ser instalada a partir da Chrome Web Store e fazer uma cópia do mesmo para uma localização diferente:

extensions.InstallExtensionHandler =
    new Handler<InstallExtensionParameters, InstallExtensionResponse>(p =>
    { 
        string name = p.ExtensionName;
        string version = p.ExtensionVersion;
        string sourceCrxFilePath = Path.GetFullPath(p.ExtensionCrxFile);
        string targetCrxFilePath = Path.GetFullPath(name + "-" + version + ".crx");
        try {
            File.Copy(sourceCrxFilePath, targetCrxFilePath);
        } catch (IOException e) {
            throw new InvalidOperationException(e);
        }
        return InstallExtensionResponse.Cancel;
    });

Agora, você pode carregar a extensão necessária na Chrome Web Store e clicar no botão “Adicionar ao Chrome”. O retorno de chamada será invocado, e o arquivo CRX da extensão será copiado para a localização especificada.