Natives Messaging

Artikel
01/19/2024

Für die Kommunikation mit einer nativen Win32-App, die auf dem Gerät eines Benutzers installiert ist, verwendet eine Erweiterung eine API, die den anderen Nachrichten über übergebende APIs ähnelt. Der native App-Host sendet und empfängt Nachrichten mit Erweiterungen mithilfe von Standardeingabe und Standardausgabe.

Erweiterungen, die natives Messaging verwenden, werden in Microsoft Edge wie jede andere Erweiterung installiert. Native Apps werden jedoch nicht von Microsoft Edge installiert oder verwaltet.

Zum Abrufen der Erweiterung und des nativen App-Hosts gibt es zwei verschiedene Verteilungsmodelle:

Packen Sie Ihre Erweiterung und den Host zusammen. Wenn ein Benutzer das Paket installiert, werden sowohl die Erweiterung als auch der Host installiert.
Oder installieren Sie Ihre Erweiterung über die Microsoft Edge-Add-Ons-Website, und Ihre Erweiterung fordert Benutzer auf, den Host zu installieren.

Führen Sie die folgenden Schritte aus, um Ihre Erweiterung zum Senden und Empfangen von Nachrichten mit nativen App-Hosts zu erstellen.

Schritt 1: Hinzufügen von Berechtigungen zum Erweiterungsmanifest

Fügen Sie der nativeMessaging Datei manifest.json der Erweiterung die Berechtigung hinzu.

Dies ist die Erweiterungsmanifestdatei, nicht die native Messaginghostmanifestdatei, die in späteren Abschnitten behandelt wird.

Es folgt eine Beispieldatei manifest.json :

Manifest V3
Manifest 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"]
}

Schritt 2: Erstellen der Manifestdatei des nativen Messaginghosts

Native Apps müssen eine native Messaginghostmanifestdatei bereitstellen. Eine Manifestdatei des nativen Messaginghosts enthält die folgenden Informationen:

Der Pfad zur nativen Messaginghostruntime.
Die Methode der Kommunikation mit der Erweiterung.
Eine Liste der zulässigen Erweiterungen, mit denen kommuniziert wird.

Der Browser liest und überprüft das native Messaginghostmanifest. Der Browser installiert oder verwaltet die Manifestdatei des nativen Messaginghosts nicht.

Die Manifestdatei des nativen Messaginghosts unterscheidet sich von der Manifest-V3- oder V2-Datei, die Teil der Microsoft Edge-Erweiterung ist.

Beispiel für eine Manifestdatei des nativen Messaginghosts:

{
    "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/"
    ]
}

Die Manifestdatei des nativen Messaginghosts muss eine gültige JSON-Datei sein, die die folgenden Schlüssel enthält:

Schlüssel	Details
`name`	Gibt den Namen des nativen Messaginghosts an. Clients übergeben die Zeichenfolge an `runtime.connectNative` oder `runtime.sendNativeMessage`. Der Wert darf nur alphanumerische Kleinbuchstaben, Unterstriche und Punkte enthalten. Der Wert darf nicht mit einem Punkt (einem Punkt) beginnen oder enden, und auf einen Punkt darf kein weiterer Punkt folgen.
`description`	Beschreibt die App.
`path`	Gibt den Pfad zur nativen Messaginghost-Binärdatei an. Auf Windows-Geräten können Sie relative Pfade zu dem Verzeichnis verwenden, das die Manifestdatei des nativen Messaginghosts enthält. Unter macOS und Linux muss der Pfad absolut sein. Der Hostprozess beginnt mit dem aktuellen Verzeichnis, das auf das Verzeichnis festgelegt ist, das die Hostbinärdatei enthält. Wenn beispielsweise (Windows) der Parameter auf `C:\App\nm_host.exe`festgelegt ist, wird die Binärdatei mit dem aktuellen Verzeichnis (`C:\App\`) gestartet.
`type`	Gibt den Typ der Schnittstelle an, die für die Kommunikation mit dem nativen Messaginghost verwendet wird. Der Wert weist Microsoft Edge an, und zu verwenden `stdin` , `stdout` um mit dem Host zu kommunizieren. Der einzige zulässige Wert ist `stdio`.
`allowed_origins`	Gibt die Liste der Erweiterungen an, die Zugriff auf den nativen Messaginghost haben. Um Ihre App zu aktivieren, um eine Erweiterung zu identifizieren und mit dieser zu kommunizieren, legen Sie in der Manifestdatei des nativen Messaginghosts den folgenden Wert fest: `"allowed_origins": ["chrome-extension://{microsoft_catalog_extension_id}"]`

Laden Sie Ihre Erweiterung quer, um natives Messaging mit dem Host zu testen. So laden Sie ihre Erweiterung während der Entwicklung quer, und rufen Sie ab microsoft_catalog_extension_id:

Wechseln Sie zu edge://extensions, und aktivieren Sie dann die Umschaltfläche für den Entwicklermodus .
Wählen Sie Entpackt laden und dann Ihr Erweiterungspaket zum Querladen aus.
Klicken Sie auf OK.
Wechseln Sie zur edge://extensions Seite, und überprüfen Sie, ob Ihre Erweiterung aufgeführt ist.
Kopieren Sie den Schlüssel aus microsoft_catalog_extension_id (ID) aus der Erweiterungsliste auf der Seite.

Wenn Sie bereit sind, Ihre Erweiterung an Benutzer zu verteilen, veröffentlichen Sie Ihre Erweiterung auf der Microsoft Edge-Add-Ons-Website. Die Erweiterungs-ID der veröffentlichten Erweiterung kann sich von der ID unterscheiden, die beim Querladen Ihrer Erweiterung verwendet wird. Wenn sich die ID geändert hat, aktualisieren Sie allowed_origins in der Manifestdatei des nativen Messaginghosts mit der ID Ihrer veröffentlichten Erweiterung.

Schritt 3: Kopieren der Manifestdatei des nativen Messaginghosts in Ihr System

Der letzte Schritt besteht darin, die native Messaginghostmanifestdatei auf Ihren Computer zu kopieren und sicherzustellen, dass diese Manifestdatei ordnungsgemäß konfiguriert ist. Führen Sie die folgenden Schritte aus, um sicherzustellen, dass die Manifestdatei des nativen Messaginghosts am erwarteten Speicherort abgelegt wird. Der Standort variiert je nach Plattform.

Unter Linux und macOS:

Stellen Sie sicher, dass Sie Leseberechtigungen für die Manifestdatei des nativen Messaginghosts bereitstellen.
Stellen Sie sicher, dass Sie Ausführungsberechtigungen für die Hostruntime bereitstellen.

Die Manifestdatei des nativen Messaginghosts kann sich an einer beliebigen Stelle im Dateisystem befinden. Das App-Installationsprogramm muss einen Registrierungsschlüssel erstellen und den Standardwert des Schlüssels auf den vollständigen Pfad der Manifestdatei des nativen Messaginghosts festlegen.

Die folgenden Speicherorte sind Beispiele für Registrierungsschlüssel:

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

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

Um dem Verzeichnis mit dem Manifestschlüssel einen Registrierungsschlüssel hinzuzufügen, führen Sie eine der folgenden Aktionen aus:

Führen Sie an der Eingabeaufforderung einen Befehl aus:

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

Oder erstellen Sie eine .reg Datei, und führen Sie sie wie folgt aus:
1. Kopieren Sie den folgenden Befehl in eine .reg Datei:
```
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. Führen Sie die Datei aus .reg . Wenn Sie die erstellte .reg Datei als Teil eines Batchskripts ausführen, stellen Sie sicher, dass Sie sie über eine Administratoreingabeaufforderung ausführen.

Microsoft Edge fragt den HKEY_CURRENT_USER Stammschlüssel ab, gefolgt von HKEY_LOCAL_MACHINE. In beiden Schlüsseln wird zuerst die 32-Bit-Registrierung und dann die 64-Bit-Registrierung durchsucht, um native Messaginghosts zu identifizieren. Der Registrierungsschlüssel gibt den Speicherort der Manifestdatei des nativen Messaginghosts an.

Wenn die Registrierungseinträge für Microsoft Edge nicht über den Speicherort der Manifestdatei des nativen Messaginghosts verfügen, werden die Chromium- und Chrome-Registrierungsspeicherorte als Fallbackoptionen verwendet.

Wenn Microsoft Edge den Registrierungsschlüssel an einem der zuvor aufgeführten Speicherorte findet, werden die im folgenden Codeausschnitt aufgeführten Speicherorte nicht abfragt.

Die Suchreihenfolge für die Registrierungsspeicherorte lautet:

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\

WOW6432Knotenregistrierungsknoten

Der HKEY_CURRENT_USER\SOFTWARE\WOW6432Node Registrierungsknoten wird auf 64-Bit-Computern aufgrund der Art und Weise, wie die Registrierung auf ihnen funktioniert, nicht durchsucht. Weitere Informationen finden Sie unter Registrierungsschlüssel, die von Windows-Installationen betroffen sind, die Unterstützung von Windows unter Windows (WOW) für Architekturen mit mehreren Prozessoren enthalten.

Für beide Speicher erforderliche Erweiterungs-IDs

Wenn Sie über Erweiterungen für die Microsoft Edge-Add-Ons und den Chrome Web Store verfügen, müssen Sie die Erweiterungs-IDs hinzufügen, die beiden Speicher in der allowed_origins Manifestdatei des nativen Messaginghosts entsprechen. Dies ist erforderlich, da nur die manifestdatei des nativen Messaginghosts gelesen wird, die dem ersten gefundenen Registrierungsspeicherort entspricht.

So speichern Sie die Manifestdatei des nativen Messaginghosts:

Systemweite native Messaginghosts, die allen Benutzern zur Verfügung stehen, werden an einem festen Speicherort gespeichert. Die Manifestdatei des nativen Messaginghosts muss beispielsweise am folgenden Speicherort gespeichert werden:
```
/Library/Microsoft/Edge/NativeMessagingHosts/com.my_company.my_app.json
```
Benutzerspezifische native Messaginghosts, die nur für den aktuellen Benutzer verfügbar sind, befinden sich im NativeMessagingHosts Unterverzeichnis des Benutzerdatenverzeichnisses. Die Manifestdatei des nativen Messaginghosts muss beispielsweise am folgenden Speicherort gespeichert werden:
```
~/Library/Application Support/Microsoft Edge {Channel_Name}/NativeMessagingHosts/com.my_company.my_app.json
```
Der {Channel_Name} in Microsoft Edge {Channel_Name} muss einer der folgenden Werte sein:
- Canary
- Dev
- Beta
Wenn Sie den stabilen Kanal verwenden, {Channel_Name} ist nicht erforderlich.

So speichern Sie die Manifestdatei des nativen Messaginghosts:

Systemweite native Messaginghosts, die allen Benutzern zur Verfügung stehen, werden an einem festen Speicherort gespeichert. Die Manifestdatei des nativen Messaginghosts muss am folgenden Speicherort gespeichert werden:
```
/etc/opt/edge/native-messaging-hosts
```
Benutzerspezifische native Messaginghosts, die nur für den aktuellen Benutzer verfügbar sind, befinden sich im NativeMessagingHosts Unterverzeichnis des Benutzerdatenverzeichnisses. Die Manifestdatei des nativen Messaginghosts muss am folgenden Speicherort gespeichert werden:
```
~/.config/microsoft-edge/NativeMessagingHosts
```

Natives Messagingprotokoll

Microsoft Edge startet jeden nativen Messaginghost in einem separaten Prozess und kommuniziert mit diesem mithilfe von Standardeingabe (stdin) und Standardausgabe (stdout). Das gleiche Format wird verwendet, um Nachrichten in beide Richtungen zu senden. Jede Nachricht wird mithilfe von JSON, UTF-8-codiert serialisiert und mit einer 32-Bit-Nachrichtenlänge in nativer Bytereihenfolge vorangestellt. Die maximale Größe einer einzelnen Nachricht vom nativen Messaginghost beträgt 1 MB, hauptsächlich um Microsoft Edge vor fehlschlagenden nativen Anwendungen zu schützen. Die maximale Größe der Nachricht, die an den nativen Messaginghost gesendet wird, beträgt 4 GB.

Das erste Argument für den nativen Messaginghost ist der Ursprung des Aufrufers, in der Regel chrome-extension://[ID of allowed extension]. Dadurch können native Messaginghosts die Quelle der Nachricht identifizieren, wenn mehrere Erweiterungen im allowed_origins Schlüssel im nativen Messaginghostmanifest angegeben sind. Weitere Informationen finden Sie oben unter Schritt 2: Erstellen der Manifestdatei des nativen Messaginghosts.

Unter Windows wird dem nativen Messaginghost auch ein Befehlszeilenargument mit einem Handle an das aufrufende native Microsoft Edge-Fenster übergeben: --parent-window=<decimal handle value>. Dadurch kann der native Messaginghost native Benutzeroberflächenfenster erstellen, die ordnungsgemäß übergeordnet sind. Beachten Sie, dass dieser Wert 0 ist, wenn der aufrufende Kontext ein Service Worker ist.

Wenn ein Messagingport mithilfe runtime.connectNativevon erstellt wird, startet Microsoft Edge einen nativen Messaginghostprozess und hält ihn so lange aktiv, bis der Port zerstört wird. Wenn hingegen eine Nachricht mit runtime.sendNativeMessagegesendet wird, ohne einen Messagingport zu erstellen, startet Microsoft Edge einen neuen systemeigenen Messaginghostprozess für jede Nachricht. In diesem Fall wird die erste Nachricht, die vom Hostprozess generiert wird, als Antwort auf die ursprüngliche Anforderung behandelt, und Microsoft Edge übergibt sie an den Antwortrückruf, der beim runtime.sendNativeMessage Aufruf angegeben wird. Alle anderen Nachrichten, die in diesem Fall vom nativen Messaginghost generiert werden, werden ignoriert.

Herstellen einer Verbindung mit einer nativen Anwendung

Das Senden und Empfangen von Nachrichten an und von einer nativen Anwendung ist dem erweiterungsübergreifenden Messaging sehr ähnlich. Der Standard Unterschied besteht darin, dass runtime.connectNative anstelle von runtime.connectruntime.sendNativeMessage und anstelle von runtime.sendMessageverwendet wird.

Um diese Methoden verwenden zu können, muss die Berechtigung in der nativeMessaging Manifestdatei Ihrer Erweiterungen deklariert werden. Siehe Schritt 1: Hinzufügen von Berechtigungen zum Erweiterungsmanifest oben.

Diese Methoden sind nicht innerhalb von Inhaltsskripts verfügbar, nur innerhalb der Seiten Ihrer Erweiterung und des Service Workers. Wenn Sie von einem Inhaltsskript mit der nativen Anwendung kommunizieren möchten, senden Sie die Nachricht an Ihren Service Worker, um sie an die native Anwendung zu übergeben.

Im folgenden Beispiel wird ein runtime.Port -Objekt erstellt, das mit dem nativen Messaginghost com.my_company.my_applicationverbunden ist, beginnt mit dem Lauschen auf Nachrichten von diesem Port und sendet eine ausgehende Nachricht:

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

Verwenden Sie runtime.sendNativeMessage , um eine Nachricht an die native Anwendung zu senden, ohne einen Port zu erstellen. Beispiel:

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

Debuggen von nativem Messaging

Wenn bestimmte systemeigene Messagingfehler auftreten, wird die Ausgabe in das Fehlerprotokoll von Microsoft Edge geschrieben. Dies schließt ein, wenn der native Messaginghost nicht gestartet werden kann, in das Kommunikationsprotokoll schreibt stderr oder gegen das Kommunikationsprotokoll verstößt. Unter Linux und macOS kann problemlos auf dieses Protokoll zugegriffen werden, indem Microsoft Edge über die Befehlszeile gestartet und die Ausgabe im Terminal überwacht wird. Verwenden Sie --enable-logging unter Windows wie unter Aktivieren der Protokollierung erläutert.

Hier sind einige häufige Fehler und Tipps zu deren Behebung:

Fehler beim Starten des nativen Messaginghosts.

Überprüfen Sie, ob Sie über ausreichende Berechtigungen zum Ausführen der nativen Messaginghostdatei verfügen.

Ungültiger nativer Messaginghostname angegeben.

Überprüfen Sie, ob der Name ungültige Zeichen enthält. Nur alphanumerische Kleinbuchstaben, Unterstriche und Punkte (Punkte) sind zulässig. Ein Name kann nicht mit einem Punkt beginnen oder enden, und auf einen Punkt kann kein weiterer Punkt folgen.

Der native Host wurde beendet.

Die Pipe an den nativen Messaginghost wurde unterbrochen, bevor die Nachricht von Microsoft Edge gelesen wurde. Dies wird höchstwahrscheinlich von Ihrem nativen Messaginghost initiiert.

Der angegebene native Messaginghost wurde nicht gefunden.

Überprüfen Sie die Folgendes:

Ist der Name in der Erweiterung und in der Manifestdatei richtig geschrieben?
Befindet sich das Manifest im richtigen Verzeichnis und mit dem richtigen Namen? Informationen zu den erwarteten Formaten finden Sie unter Standort des nativen Messaginghosts .
Hat die Manifestdatei das richtige Format? Insbesondere ist der JSON-Code gültig und wohlgeformt, und stimmen die Werte mit der Definition eines nativen Messaginghostmanifests gemäß Schritt 2: Erstellen Ihrer nativen Messaginghostmanifestdatei oben überein?
Ist die in path angegebene Datei vorhanden? Unter Windows können Pfade relativ sein, aber unter macOS und Linux müssen die Pfade absolut sein.

Der Hostname des nativen Messaginghosts ist nicht registriert. (nur Windows)

Der native Messaginghost wurde in der Windows-Registrierung nicht gefunden. Überprüfen Sie regedit , ob der Schlüssel wirklich erstellt wurde und mit dem erforderlichen Format übereinstimmt, wie am Standort des nativen Messaginghosts dokumentiert.

Der Zugriff auf den angegebenen nativen Messaginghost ist verboten.

Ist der Ursprung der Erweiterung in allowed_originsaufgeführt?

Fehler bei der Kommunikation mit dem nativen Messaginghost.

Dies deutet auf eine falsche Implementierung des Kommunikationsprotokolls auf dem nativen Messaginghost hin.

Stellen Sie sicher, dass alle Ausgaben in stdout dem nativen Messagingprotokoll entsprechen. Wenn Sie einige Daten zu Debugzwecken drucken möchten, schreiben Sie in stderr.
Stellen Sie sicher, dass die 32-Bit-Nachrichtenlänge im nativen ganzzahligen Format der Plattform (Little-Endian oder Big-Endian) liegt.
Die Nachrichtenlänge darf 1024* 1024 nicht überschreiten.
Die Nachrichtengröße muss der Anzahl von Bytes in der Nachricht entsprechen. Dies kann sich von der "Länge" einer Zeichenfolge unterscheiden, da Zeichen durch mehrere Bytes dargestellt werden können.
Nur Windows: Stellen Sie sicher, dass der E/A-Modus des Programms auf O_BINARYfestgelegt ist. Standardmäßig ist der E/A-Modus , wodurch das Nachrichtenformat beschädigt wird O_TEXT, da Zeilenumbrüche (\n = 0A) durch Zeilenenden im Windows-Stil (\r\n = 0D 0A) ersetzt werden. Der E/A-Modus kann mithilfe __setmodevon festgelegt werden.

Hinweis

Teile dieser Seite sind Änderungen, die auf Arbeiten basieren, die von Google erstellt und geteilt und gemäß den in der Creative Commons Attribution 4.0 International License beschriebenen Bedingungen verwendet werden. Die ursprüngliche Seite finden Sie hier.

Dieses Werk ist unter einer Creative Commons Attribution 4.0 International License lizenziert.

Freigeben über