Mensagens nativas

2025-06-26

Para comunicar com uma aplicação Win32 nativa instalada no dispositivo de um utilizador, uma extensão utiliza uma API semelhante à outra mensagem que transmite APIs. O anfitrião da aplicação nativa envia e recebe mensagens com extensões através da entrada padrão e da saída padrão.

As extensões que utilizam mensagens nativas são instaladas no Microsoft Edge de forma semelhante a qualquer outra extensão. No entanto, as aplicações nativas não são instaladas ou geridas pelo Microsoft Edge.

Para adquirir a extensão e o anfitrião de aplicações nativos, existem dois modelos de distribuição diferentes:

Empacote a extensão e o anfitrião em conjunto. Quando um utilizador instala o pacote, a extensão e o anfitrião são instalados.
Em alternativa, instale a extensão a partir dos Suplementos do Microsoft Edge e a extensão pede aos utilizadores para instalarem o anfitrião.

Para criar a extensão para enviar e receber mensagens com anfitriões de aplicações nativos, siga os seguintes passos.

Passo 1: adicionar permissões ao manifesto da extensão

Adicione a nativeMessaging permissão ao ficheiro manifest.json da extensão.

Este é o ficheiro de manifesto da extensão, não o ficheiro de manifesto do anfitrião de mensagens nativo, que é abordado em secções posteriores.

Segue-se um exemplo manifest.json ficheiro:

Manifesto V3
Manifesto V2

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 3,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 2,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

Passo 2: Criar o ficheiro de manifesto do anfitrião de mensagens nativo

As aplicações nativas têm de fornecer um ficheiro de manifesto do anfitrião de mensagens nativo. Um ficheiro de manifesto do anfitrião de mensagens nativo contém as seguintes informações:

O caminho para o runtime do anfitrião de mensagens nativo.
O método de comunicação com a extensão.
Uma lista de extensões permitidas às quais comunica.

O browser lê e valida o manifesto do anfitrião de mensagens nativo. O browser não instala nem gere o ficheiro de manifesto do anfitrião de mensagens nativo.

O ficheiro de manifesto do anfitrião de mensagens nativo é diferente do ficheiro V3 ou V2 do Manifesto que faz parte da extensão do Microsoft Edge.

Exemplo de um ficheiro de manifesto do anfitrião de mensagens nativo:

{
    "name": "com.my_company.my_app",
    "description": "My App",
    "path": "C:\\Program Files\\My App\\chrome_native_messaging_host.exe",
    "type": "stdio",
    "allowed_origins": [
        "chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"
    ]
}

O ficheiro de manifesto do anfitrião de mensagens nativo tem de ser um ficheiro JSON válido que contenha as seguintes chaves:

Chave	Detalhes
`name`	Especifica o nome do anfitrião de mensagens nativo. Os clientes transmitem a cadeia para `runtime.connectNative` ou `runtime.sendNativeMessage`. O valor só tem de conter carateres alfanuméricos em minúsculas, carateres de sublinhado e pontos. O valor não pode começar ou terminar com um ponto (um ponto) e um ponto não pode ser seguido por outro ponto.
`description`	Descreve a aplicação.
`path`	Especifica o caminho para o binário do anfitrião de mensagens nativo. Em dispositivos Windows, pode utilizar caminhos relativos para o diretório que contém o ficheiro de manifesto do anfitrião de mensagens nativo. No macOS e Linux, o caminho tem de ser absoluto. O processo de anfitrião começa com o diretório atual definido para o diretório que contém o binário do anfitrião. Por exemplo (Windows), se o parâmetro estiver definido como `C:\App\nm_host.exe`, o binário é iniciado com o diretório atual (`C:\App\`).
`type`	Especifica o tipo da interface utilizada para comunicar com o anfitrião de mensagens nativo. O valor indica ao Microsoft Edge para utilizar `stdin` e `stdout` comunicar com o anfitrião. O único valor aceitável é `stdio`.
`allowed_origins`	Especifica a lista de extensões que têm acesso ao anfitrião de mensagens nativo. Para ativar a aplicação para identificar e comunicar com uma extensão, no ficheiro de manifesto do anfitrião de mensagens nativo, defina o seguinte valor: `"allowed_origins": ["chrome-extension://{microsoft_catalog_extension_id}"]`

Faça sideload da extensão para testar mensagens nativas com o anfitrião. Para fazer sideload da extensão durante o desenvolvimento e obter microsoft_catalog_extension_id:

Aceda a edge://extensionse, em seguida, ative o botão de alternar Modo de programador.
Selecione Carregar desembalado e, em seguida, selecione o pacote de extensão para sideload.
Clique em OK.
Aceda à página e verifique se a edge://extensions extensão está listada.
Copie a chave de microsoft_catalog_extension_id (ID) da listagem de extensões na página.

Quando estiver pronto para distribuir a extensão aos utilizadores, publique a extensão nos Suplementos do Microsoft Edge. O ID de extensão da extensão publicada pode ser diferente do ID utilizado durante o sideload da extensão. Se o ID tiver sido alterado, atualize allowed_origins no ficheiro de manifesto do anfitrião de mensagens nativo com o ID da extensão publicada.

Passo 3: copiar o ficheiro de manifesto do anfitrião de mensagens nativo para o seu sistema

O passo final envolve copiar o ficheiro de manifesto do anfitrião de mensagens nativo para o computador e certificar-se de que este ficheiro de manifesto está configurado corretamente. Para garantir que o ficheiro de manifesto do anfitrião de mensagens nativo é colocado na localização esperada, siga os seguintes passos. A localização varia de acordo com a plataforma.

No Linux e macOS:

Certifique-se de que fornece permissões de leitura no ficheiro de manifesto do anfitrião de mensagens nativo.
Certifique-se de que fornece permissões de execução no runtime do anfitrião.

O ficheiro de manifesto do anfitrião de mensagens nativo pode estar localizado em qualquer parte do sistema de ficheiros. O instalador de aplicações tem de criar uma chave de registo e definir o valor predefinido da chave para o caminho completo do ficheiro de manifesto do anfitrião de mensagens nativo.

As seguintes localizações são exemplos de chaves de registo:

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

Para adicionar uma chave de registo ao diretório com a chave de manifesto, efetue um dos seguintes procedimentos:

Execute um comando na linha de comandos:

REG ADD "HKCU\Software\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f

Em alternativa, crie um .reg ficheiro e execute-o da seguinte forma:
1. Copie o seguinte comando para um .reg ficheiro:
```
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app]
@="C:\\path\\to\\nmh-manifest.json"
```
2. Execute o .reg ficheiro. Se executar o ficheiro criado .reg como parte de um script de lote, certifique-se de que o executa com uma linha de comandos de administrador.

O Microsoft Edge consulta a HKEY_CURRENT_USER chave raiz, seguida de HKEY_LOCAL_MACHINE. Em ambas as chaves, o registo de 32 bits é procurado primeiro e, em seguida, o registo de 64 bits é procurado para identificar anfitriões de mensagens nativos. A chave do registo especifica a localização do ficheiro de manifesto do anfitrião de mensagens nativo.

Se as entradas de registo do Microsoft Edge não tiverem a localização do ficheiro de manifesto do anfitrião de mensagens nativo, as localizações do registo Chromium e chrome são utilizadas como opções de contingência.

Se o Microsoft Edge encontrar a chave de registo em qualquer uma das localizações listadas anteriormente, não consultará as localizações listadas no fragmento de código seguinte.

A ordem de pesquisa das localizações do registo é:

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\

Nó de registo WOW6432Node

O HKEY_CURRENT_USER\SOFTWARE\WOW6432Node nó de registo não é pesquisado em computadores de 64 bits, devido à forma como o registo funciona nos mesmos. Para obter mais informações, veja Chaves de Registo Afetadas pelas Instalações do Windows que Incluem Suporte do Windows no Windows (WOW) para Arquiteturas de Processador Múltiplas.

IDs de extensão necessários para ambas as lojas

Se tiver uma extensão nos Suplementos do Microsoft Edge e na Chrome Web Store, tem de adicionar os IDs de extensão que correspondem a ambas as lojas no allowed_origins ficheiro de manifesto do anfitrião de mensagens nativo.

Isto é necessário porque apenas o ficheiro de manifesto do anfitrião de mensagens nativo que corresponde à primeira localização de registo encontrada é lido.

Para armazenar o ficheiro de manifesto do anfitrião de mensagens nativo:

Os anfitriões de mensagens nativos em todo o sistema, que estão disponíveis para todos os utilizadores, são armazenados numa localização fixa. Por exemplo, o ficheiro de manifesto do anfitrião de mensagens nativo tem de ser armazenado na seguinte localização:
```
/Library/Microsoft/Edge/NativeMessagingHosts/com.my_company.my_app.json
```
Os anfitriões de mensagens nativos específicos do utilizador, que estão disponíveis apenas para o utilizador atual, estão localizados no NativeMessagingHosts subdiretório no diretório de dados do utilizador. Por exemplo, o ficheiro de manifesto do anfitrião de mensagens nativo tem de ser armazenado na seguinte localização:
```
~/Library/Application Support/Microsoft Edge {Channel_Name}/NativeMessagingHosts/com.my_company.my_app.json
```
O {Channel_Name} in Microsoft Edge {Channel_Name} tem de ser um dos seguintes valores:
- Canary
- Dev
- Beta
Ao utilizar o canal Estável, {Channel_Name} não é necessário.

Confira:

Diretório de Dados de Utilizador no Chromium documentos.

Para armazenar o ficheiro de manifesto do anfitrião de mensagens nativo:

Os anfitriões de mensagens nativos em todo o sistema, que estão disponíveis para todos os utilizadores, são armazenados numa localização fixa. O ficheiro de manifesto do anfitrião de mensagens nativo tem de ser armazenado na seguinte localização:
```
/etc/opt/edge/native-messaging-hosts
```
Os anfitriões de mensagens nativos específicos do utilizador, que estão disponíveis apenas para o utilizador atual, estão localizados no NativeMessagingHosts subdiretório no diretório de dados do utilizador. O ficheiro de manifesto do anfitrião de mensagens nativo tem de ser armazenado na seguinte localização:
```
~/.config/microsoft-edge/NativeMessagingHosts
```

Confira:

Diretório de Dados de Utilizador no Chromium documentos.

Protocolo de mensagens nativas

O Microsoft Edge inicia cada anfitrião de mensagens nativo num processo separado e comunica com o mesmo através da entrada padrão (stdin) e da saída padrão (stdout). O mesmo formato é utilizado para enviar mensagens em ambas as direções; cada mensagem é serializada com JSON, CODIFICADO UTF-8 e é precedida com o comprimento da mensagem de 32 bits por ordem de bytes nativos. O tamanho máximo de uma única mensagem do anfitrião de mensagens nativo é de 1 MB, principalmente para proteger o Microsoft Edge de aplicações nativas que se comportam incorretamente. O tamanho máximo da mensagem enviada para o anfitrião de mensagens nativo é de 4 GB.

O primeiro argumento para o anfitrião de mensagens nativo é a origem do autor da chamada, normalmente chrome-extension://[ID of allowed extension]. Isto permite que os anfitriões de mensagens nativos identifiquem a origem da mensagem quando são especificadas várias extensões na allowed_origins chave no manifesto do anfitrião de mensagens nativo. Consulte o Passo 2: Criar o ficheiro de manifesto do anfitrião de mensagens nativo acima.

No Windows, o anfitrião de mensagens nativo também é transmitido um argumento de linha de comandos com uma alça para a janela nativa do Microsoft Edge: --parent-window=<decimal handle value>. Isto permite que o anfitrião de mensagens nativo crie janelas de IU nativas que são corretamente parentadas. Este valor será 0 se o contexto de chamada for uma função de trabalho de serviço.

Quando uma porta de mensagens é criada com runtime.connectNativeo , o Microsoft Edge inicia um processo de anfitrião de mensagens nativo e mantém-no em execução até que a porta seja destruída. Por outro lado, quando uma mensagem é enviada através runtime.sendNativeMessagedo , sem criar uma porta de mensagens, o Microsoft Edge inicia um novo processo de anfitrião de mensagens nativo para cada mensagem. Nesse caso, a primeira mensagem gerada pelo processo de anfitrião é processada como uma resposta ao pedido original e o Microsoft Edge irá transmiti-la para a chamada de retorno de resposta especificada quando runtime.sendNativeMessage é chamada. Todas as outras mensagens geradas pelo anfitrião de mensagens nativo nesse caso são ignoradas.

Ligar a uma aplicação nativa

Enviar e receber mensagens de e para uma aplicação nativa é muito semelhante às mensagens entre extensões. A diferença main é que runtime.connectNative é utilizada em vez de runtime.connecte runtime.sendNativeMessage é utilizada em vez de runtime.sendMessage.

Para utilizar estes métodos, a nativeMessaging permissão tem de ser declarada no ficheiro de manifesto das extensões; consulte o Passo 1: Adicionar permissões ao manifesto de extensão acima.

Estes métodos não estão disponíveis nos scripts de conteúdo, apenas nas páginas da extensão e na função de trabalho de serviço. Se quiser comunicar a partir de um script de conteúdo para a aplicação nativa, envie a mensagem para a sua função de trabalho de serviço para passá-la para a aplicação nativa.

O exemplo seguinte cria um runtime.Port objeto que está ligado ao anfitrião com.my_company.my_applicationde mensagens nativo, começa a escutar mensagens dessa porta e envia uma mensagem a enviar:

var port = chrome.runtime.connectNative('com.my_company.my_application');
port.onMessage.addListener(function (msg) {
  console.log('Received' + msg);
});
port.onDisconnect.addListener(function () {
  console.log('Disconnected');
});
port.postMessage({text: 'Hello, my_application'});

Utilize runtime.sendNativeMessage para enviar uma mensagem para a aplicação nativa sem criar uma porta; por exemplo:

chrome.runtime.sendNativeMessage(
  'com.my_company.my_application',
  {text: 'Hello'},
  function (response) {
    console.log('Received ' + response);
  }
);

Depurar mensagens nativas

Quando ocorrem determinadas falhas de mensagens nativas, a saída é escrita no registo de erros do Microsoft Edge. Isto inclui quando o anfitrião de mensagens nativo não inicia, escreve stderr ou viola o protocolo de comunicação. No Linux e macOS, este registo pode ser facilmente acedido iniciando o Microsoft Edge a partir da linha de comandos e observando o respetivo resultado no terminal. No Windows, utilize --enable-logging como explicado em Como ativar o registo.

Seguem-se alguns erros comuns e sugestões para os resolver:

Falha ao iniciar o anfitrião de mensagens nativo.

Verifique se tem permissões suficientes para executar o ficheiro anfitrião de mensagens nativo.

Foi especificado um nome de anfitrião de mensagens nativo inválido.

Verifique se o nome contém carateres inválidos. Só são permitidos carateres alfanuméricos em minúsculas, carateres de sublinhado e pontos (períodos). Um nome não pode começar ou terminar com um ponto e um ponto não pode ser seguido por outro ponto.

O anfitrião nativo foi encerrado.

O pipe para o anfitrião de mensagens nativo foi quebrado antes de a mensagem ser lida pelo Microsoft Edge. Isto é provavelmente iniciado a partir do seu anfitrião de mensagens nativo.

O anfitrião de mensagens nativo especificado não foi encontrado.

Verificar o seguinte:

O nome está escrito corretamente na extensão e no ficheiro de manifesto?
O manifesto está no diretório correto e com o nome correto? Veja a localização do anfitrião de mensagens nativa para obter os formatos esperados.
O ficheiro de manifesto está no formato correto? Em particular, o JSON é válido e bem formado e os valores correspondem à definição de um manifesto de anfitrião de mensagens nativo, por Passo 2: Criar o ficheiro de manifesto do anfitrião de mensagens nativo acima?
O ficheiro especificado em path existe? No Windows, os caminhos podem ser relativos, mas no macOS e Linux, os caminhos têm de ser absolutos.

O nome do anfitrião do anfitrião de mensagens nativo não está registado. (apenas no Windows)

O anfitrião de mensagens nativo não foi encontrado no registo do Windows. Faça duplo marcar utilizando regedit se a chave foi realmente criada e corresponde ao formato necessário, conforme documentado na localização do anfitrião de mensagens nativa.

O acesso ao anfitrião de mensagens nativo especificado é proibido.

A origem da extensão está listada em allowed_origins?

Erro ao comunicar com o anfitrião de mensagens nativo.

Isto indica uma implementação incorreta do protocolo de comunicação no anfitrião de mensagens nativo.

Certifique-se de que todos os resultados no stdout cumprem o protocolo de mensagens nativo. Se quiser imprimir alguns dados para fins de depuração, escreva em stderr.
Certifique-se de que o comprimento da mensagem de 32 bits está no formato inteiro nativo da plataforma (little-endian ou big-endian).
O comprimento da mensagem não pode exceder 1024*1024.
O tamanho da mensagem tem de ser igual ao número de bytes na mensagem. Isto pode diferir do "comprimento" de uma cadeia, porque os carateres podem ser representados por vários bytes.
Apenas windows: Certifique-se de que o modo de E/S do programa está definido como O_BINARY. Por predefinição, o modo de E/S é O_TEXT, que danifica o formato da mensagem à medida que as quebras de linha (0A = \n) são substituídas por terminações de linha estilo Windows ().\r\n = 0D 0A O modo de E/S pode ser definido com __setmode.

Observação

Partes desta página são modificações baseadas no trabalho criado e partilhado pela Google e utilizado de acordo com os termos descritos na Licença Internacional Creative Commons Attribution 4.0. A página original encontra-se aqui.

Este trabalho é licenciado ao abrigo de uma Licença Internacional creative Commons Attribution 4.0.

Compartilhar via