原生訊息

要與安裝在使用者裝置上的原生 Win32 應用程式溝通，擴充功能會使用類似其他 訊息傳遞 API 的 API。 原生應用程式主機透過標準輸入與輸出發送與接收帶有擴充功能的訊息。

使用原生訊息功能的擴充功能會安裝在 Microsoft Edge 中，與其他擴充功能類似。 然而，原生應用程式並非由 Microsoft Edge 安裝或管理。

為了取得擴充功能與原生應用程式主機，有兩種不同的發行模式：

• 把你的擴充功能和主機一起打包。 當使用者安裝套件時，擴充功能與主機都會被安裝。

• 或者，從 Microsoft Edge Add-ons 安裝你的擴充功能，你的擴充功能會提示使用者安裝主機。

要建立與原生應用程式主機發送和接收訊息的擴充功能，請執行以下步驟。

步驟 1：將權限加入擴充功能清單

將權限加入 nativeMessaging 擴充功能的 manifest.json 檔案。

這是 副名清單檔案，而非 原生訊息主機清單檔案，後者會在後面章節中介紹。

以下是 manifest.json 檔案的範例：

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

步驟二：建立你的原生訊息主機清單檔案

原生應用程式必須提供原生訊息主機清單檔案。 原生訊息主機清單檔案包含以下資訊：

• 通往原生訊息主機執行時的路徑。

• 與分機的溝通方式。

• 一份允許的延伸清單，該擴充功能可通訊。

瀏覽器會讀取並驗證原生訊息主機清單。 瀏覽器不會安裝或管理原生的訊息主機清單檔案。

原生訊息主機清單檔案與 Microsoft Edge 擴充功能中的 Manifest V3 或 V2 檔案是不同的。

原生訊息主機清單檔案範例：

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

原生訊息主機清單檔案必須是包含以下金鑰的有效 JSON 檔案：

側載你的擴充功能，測試主機的原生訊息。 在開發過程中側載擴充功能並取回 microsoft_catalog_extension_id：

1. 前往 edge://extensions，然後開啟 開發者模式 切換按鈕。

2. 選擇 「載入解包」，然後選擇你的擴充套件來側載。

3. 按一下確定。

4. 請前往該 edge://extensions 頁面確認你的分機是否被列出。

5. 從頁面上的擴充功能列表複製 (ID) 的金鑰 microsoft_catalog_extension_id 。

當你準備好將擴充功能分發給使用者時，請在 Microsoft Edge Add-ons 發佈你的擴充功能。 已發佈擴充功能的擴充 ID 可能和側載擴充功能時使用的 ID 不同。 如果 ID 變更，請在原生訊息主機清單檔中更新 allowed_origins 你已發布的副檔名的 ID。

步驟 3：將原生訊息主機清單檔案複製到你的系統

最後一步是將原生的訊息主機清單檔案複製到你的電腦，並確保這個清單檔案是正確設定的。 為了確保您的原生訊息主機清單檔案被放置在預期位置，請採取以下步驟。 地點會依月台而異。

在 Linux 和 macOS 上：

• 務必在原生訊息主機清單檔案上提供 讀取 權限。
• 確保你在主機執行時提供 執行 權限。

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

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

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\

原生訊息協定

Microsoft Edge 會以獨立程序啟動每個原生訊息主機，並以標準輸入 (stdin) 與標準輸出) (stdout 與主機通訊。 相同格式用於雙向傳送訊息;每則訊息皆以 JSON、UTF-8 編碼序列化，且前置訊息長度為原生位元組序的 32 位元。 來自原生訊息主機的單一訊息最大容量為 1 MB，主要是為了保護 Microsoft Edge 避免原生應用程式出現異常行為。 發送給原生訊息主機的訊息最大容量為 4 GB。

對本地訊息主機的第一個論點是呼叫者的來源，通常是 chrome-extension://[ID of allowed extension]。 這讓原生訊息主機能夠在本地訊息主機清單中金鑰中指定 allowed_origins 多個副檔名時，識別訊息來源;詳見上方 步驟 2：建立您的原生訊息主機清單檔案。

在 Windows 上，原生訊息主機也會被傳遞一個命令列參數，並帶有一個句柄，連接到呼叫的 Microsoft Edge 原生視窗： --parent-window=<decimal handle value>。 這讓原生訊息主機能建立正確父級的原生 UI 視窗。 若呼叫上下文為服務工作者，該值將為 0。

當使用 runtime.connectNative， 建立訊息埠時，Microsoft Edge 會啟動原生訊息主機程序，並持續運行直到埠被摧毀。 另一方面，當訊息以 發送 runtime.sendNativeMessage且未建立訊息埠時，Microsoft Edge 會為每則訊息啟動新的原生訊息主機程序。 在這種情況下，主機程序產生的第一則訊息會被當作對原始請求的回應處理，Microsoft Edge 會在呼叫時 runtime.sendNativeMessage 將其轉交給指定的回應回調。 在這種情況下，原生訊息主機產生的所有其他訊息都會被忽略。

連接原生應用程式

與原生應用程式之間的訊息發送與接收，與跨分機訊息非常相似。 主要差異在於 是 runtime.connectNative ，runtime.connect取代了 ，而 runtime.sendNativeMessage 是 ，而 是 ，runtime.sendMessage而 。

要使用這些方法， nativeMessaging 必須在擴充套件的清單檔案中宣告權限;詳見上 文步驟 1：向擴充功能清單新增權限。

這些方法不存在於內容腳本中，只有在擴充功能的頁面和服務工作者中才有。 如果你想從內容腳本與原生應用程式溝通，請將訊息傳給你的服務人員，讓他轉交給原生應用程式。

以下範例 runtime.Port 建立一個物件，連接到原生訊息主機 com.my_company.my_application，開始監聽該埠的訊息並發送一則外發訊息：

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

用於 runtime.sendNativeMessage 傳送訊息給原生應用程式而無需建立埠口;例如：

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

除錯原生訊息

當發生某些原生訊息失敗時，輸出會寫入 Microsoft Edge 的錯誤日誌。 這包括當原生訊息主機無法啟動、寫入 stderr 或違反通訊協定時。 在 Linux 和 macOS 上，只要從命令列啟動 Microsoft Edge 並在終端機中觀看輸出，就能輕鬆存取這份日誌。 在 Windows 上，請依照「如何啟用日誌」的說明使用--enable-logging。

以下是一些常見錯誤與解決建議：

無法啟動原生訊息主機。

檢查你是否有足夠的權限來執行原生訊息主機檔案。

指定無效的原生訊息主機名稱。

檢查名稱是否包含無效字元。 僅允許使用小寫字母數字、底線和點 () 句點。 名字不能以點開頭或結尾，點後面也不能接著另一個點。

原生主機已退出。

在 Microsoft Edge 讀取訊息之前，該管道就已經被破壞。 這很可能是從你原生的訊息主機發起的。

找不到指定的原生訊息主機。

請檢查下列項目：

• 副檔名和清單檔案裡的名字拼寫正確嗎？

• 清單是否在正確的目錄中，且名稱正確？ 請參閱 原生訊息主機位置 以了解預期格式。

• 清單檔案格式正確嗎？ 特別是，JSON 是否有效且格式良好？這些值是否符合上述步驟 2：建立你的原生訊息主機清單檔案的定義？

• 裡面指定的 path 檔案存在嗎？ 在 Windows 上，路徑可能是相對的，但在 macOS 和 Linux 上，路徑必須是絕對的。

原生 訊息主機名稱 未被註冊。 (僅限 Windows)

原生訊息主機並未在 Windows 登錄檔中找到。 請再次確認 regedit 金鑰是否真的被建立，且格式是否符合 原生訊息主機位置所記載的格式。

禁止存取指定的原生訊息主機。

該擴展的來源是否列在 allowed_origins？

與原生訊息主機通訊時出現錯誤。

這表示原生訊息主機對通訊協定的實作不正確。

• 確保所有輸出 stdout 都遵循 原生訊息協定。 如果你想列印一些資料以便除錯，寫入 stderr。

• 確保 32 位元訊息長度是平台原生整數格式 (小端序或大端序) 。

• 訊息長度不得超過 1024×1024。

• 訊息大小必須等於訊息中的位元組數。 這可能與字串的「長度」不同，因為字元可能由多個位元組表示。

• 僅限 Windows 支援： 確保程式的 I/O 模式設定為 O_BINARY。 預設的 I/O 模式為 O_TEXT，該模式會破壞訊息格式，因為換行 ( = 0A\n) 會被 Windows 風格的行尾取代 (\r\n = 0D 0A) 。 輸入輸出模式可透過使用 __setmode。

本作品採用 創用CC 姓名標示4.0國際授權條款授權。