Собственные сообщения

2025-06-26

Для взаимодействия с собственным приложением Win32, установленным на устройстве пользователя, расширение использует API, аналогичный другому сообщению, передаваемого API. Узел собственного приложения отправляет и получает сообщения с расширениями, используя стандартные входные и стандартные выходные данные.

Расширения, использующие собственный обмен сообщениями, устанавливаются в Microsoft Edge аналогично любому другому расширению. Однако microsoft Edge не устанавливает собственные приложения и не управляет ими.

Чтобы получить расширение и собственный узел приложения, существуют две разные модели распространения:

Упаковайте расширение и узел вместе. Когда пользователь устанавливает пакет, устанавливаются как расширение, так и узел.
Или установите расширение из надстроек Microsoft Edge, и ваше расширение предложит пользователям установить узел.

Чтобы создать расширение для отправки и получения сообщений с собственными узлами приложений, выполните следующие действия.

Шаг 1. Добавление разрешений для манифеста расширения

nativeMessaging Добавьте разрешение в файл manifest.json расширения.

Это файл манифеста расширения, а не собственный файл манифеста узла обмена сообщениями, который рассматривается в последующих разделах.

Ниже приведен пример файла manifest.json :

Манифест версии 3
Манифест версии 2

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

Шаг 2. Создание собственного файла манифеста узла обмена сообщениями

Собственные приложения должны предоставлять собственный файл манифеста узла обмена сообщениями. Файл манифеста узла собственного обмена сообщениями содержит следующие сведения:

Путь к собственной среде выполнения узла обмена сообщениями.
Метод связи с расширением.
Список разрешенных расширений, с которыми он взаимодействует.

Браузер считывает и проверяет собственный манифест узла обмена сообщениями. Браузер не устанавливает собственный файл манифеста узла обмена сообщениями и не управляет им.

Собственный файл манифеста узла обмена сообщениями отличается от файла манифеста версии 3 или версии 2, который является частью расширения Microsoft Edge.

Пример собственного файла манифеста узла обмена сообщениями:

{
    "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-файлом, который содержит следующие ключи:

Key	Сведения
`name`	Указывает имя собственного узла обмена сообщениями. Клиенты передают строку в `runtime.connectNative` или `runtime.sendNativeMessage`. Значение должно содержать только буквенно-цифровые символы в нижнем регистре, символы подчеркивания и точки. Значение не должно начинаться или заканчиваться точкой (точкой), а за точкой не должна следовать другая точка.
`description`	Описывает приложение.
`path`	Указывает путь к двоичному файлу собственного узла обмена сообщениями. На устройствах Windows можно использовать относительные пути к каталогу, содержащему собственный файл манифеста узла обмена сообщениями. В macOS и Linux путь должен быть абсолютным. Процесс узла начинается с текущего каталога, задается каталог, содержащий двоичный файл узла. Например (Windows), если параметр имеет значение `C:\App\nm_host.exe`, двоичный файл запускается с помощью текущего каталога (`C:\App\`).
`type`	Указывает тип интерфейса, используемого для взаимодействия с собственным узлом обмена сообщениями. Значение указывает Microsoft Edge на использование `stdin` узла и `stdout` взаимодействие с ним. Единственное допустимое значение — `stdio`.
`allowed_origins`	Указывает список расширений, имеющих доступ к собственному узлу обмена сообщениями. Чтобы включить приложение для идентификации расширения и взаимодействия с ним, в файле манифеста собственного узла обмена сообщениями задайте следующее значение: `"allowed_origins": ["chrome-extension://{microsoft_catalog_extension_id}"]`

Загрузите неопубликованное расширение, чтобы протестировать собственный обмен сообщениями с узлом. Загрузка неопубликованного расширения во время разработки и получение microsoft_catalog_extension_id:

Перейдите в edge://extensions, а затем включите переключатель режим разработчика .
Выберите Загрузить неупакованный, а затем выберите пакет расширения для загрузки неопубликованного файла.
Нажмите кнопку OK.
Перейдите на страницу edge://extensions и убедитесь, что ваше расширение указано.
Скопируйте ключ из microsoft_catalog_extension_id (id) из списка расширений на странице.

Когда вы будете готовы распространить расширение среди пользователей, опубликуйте его в надстройках Microsoft Edge. Идентификатор расширения опубликованного расширения может отличаться от идентификатора, используемого при загрузке неопубликованного расширения. Если идентификатор изменился, обновите allowed_origins в собственном файле манифеста узла обмена сообщениями идентификатор опубликованного расширения.

Шаг 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

Чтобы добавить раздел реестра в каталог с ключом манифеста, выполните одно из следующих действий:

Выполните команду в командной строке:

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

Или создайте .reg файл и запустите его следующим образом:
1. Скопируйте следующую .reg команду в файл:
```
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. .reg Запустите файл. Если вы запускаете созданный .reg файл как часть пакетного сценария, убедитесь, что вы запускаете его с помощью командной строки администратора.

Microsoft Edge запрашивает корневой HKEY_CURRENT_USER ключ, за которым следует HKEY_LOCAL_MACHINE. В обоих разделах сначала выполняется поиск в 32-разрядном реестре, а затем выполняется поиск в 64-разрядном реестре, чтобы определить собственные узлы обмена сообщениями. Раздел реестра указывает расположение файла манифеста собственного узла обмена сообщениями.

Если в записях реестра для Microsoft Edge нет файла манифеста собственного узла обмена сообщениями, в качестве резервных вариантов используются расположения реестра Chromium и Chrome.

Если Microsoft Edge находит раздел реестра в любом из перечисленных ранее расположений, он не запрашивает расположения, перечисленные в следующем фрагменте кода.

Порядок поиска расположений реестра:

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\

Узел реестра WOW6432Node

Узел HKEY_CURRENT_USER\SOFTWARE\WOW6432Node реестра не выполняется на 64-разрядных компьютерах из-за того, как реестр работает с ними. Дополнительные сведения см. в разделе Разделы реестра, затронутые установками Windows, включающими поддержку Windows в Windows (WOW) для архитектур нескольких процессоров.

Идентификаторы расширений, необходимые для обоих хранилищ

Если у вас есть расширение как в надстройках Microsoft Edge , так и в веб-магазине Chrome, необходимо добавить идентификаторы расширений, соответствующие обоим хранилищам , в allowed_origins файл манифеста собственного узла обмена сообщениями.

Это необходимо, так как считывается только собственный файл манифеста узла обмена сообщениями, соответствующий первому найденому расположению реестра.

Чтобы сохранить собственный файл манифеста узла обмена сообщениями, выполните следующие действия:

Узлы обмена сообщениями на уровне системы, доступные всем пользователям, хранятся в фиксированном расположении. Например, собственный файл манифеста узла обмена сообщениями должен храниться в следующем расположении:
```
/Library/Microsoft/Edge/NativeMessagingHosts/com.my_company.my_app.json
```
Собственные узлы обмена сообщениями, доступные только текущему пользователю, находятся в подкаталоге NativeMessagingHosts в каталоге пользовательских данных. Например, собственный файл манифеста узла обмена сообщениями должен храниться в следующем расположении:
```
~/Library/Application Support/Microsoft Edge {Channel_Name}/NativeMessagingHosts/com.my_company.my_app.json
```
Значение {Channel_Name} in Microsoft Edge {Channel_Name} должно иметь одно из следующих значений:
- Canary
- Dev
- Beta
При использовании стабильного канала {Channel_Name} не требуется.

См. следующие статьи:

Каталог данных пользователя в Chromium документации.

Чтобы сохранить собственный файл манифеста узла обмена сообщениями, выполните следующие действия:

Узлы обмена сообщениями на уровне системы, доступные всем пользователям, хранятся в фиксированном расположении. Файл манифеста узла собственных сообщений должен храниться в следующем расположении:
```
/etc/opt/edge/native-messaging-hosts
```
Собственные узлы обмена сообщениями, доступные только текущему пользователю, находятся в подкаталоге NativeMessagingHosts в каталоге пользовательских данных. Файл манифеста узла собственных сообщений должен храниться в следующем расположении:
```
~/.config/microsoft-edge/NativeMessagingHosts
```

См. следующие статьи:

Каталог данных пользователя в Chromium документации.

Собственный протокол обмена сообщениями

Microsoft Edge запускает каждый собственный узел обмена сообщениями в отдельном процессе и взаимодействует с ним с помощью стандартных входных данных (stdin) и стандартных выходных данных (stdout). Один и тот же формат используется для отправки сообщений в обоих направлениях; каждое сообщение сериализуется с помощью JSON в кодировке UTF-8 и предшествует 32-разрядной длине сообщения в собственном порядке байтов. Максимальный размер одного сообщения с собственного узла обмена сообщениями составляет 1 МБ, главным образом для защиты Microsoft Edge от неправильного поведения собственных приложений. Максимальный размер сообщения, отправляемого на собственный узел обмена сообщениями, составляет 4 ГБ.

Первым аргументом для собственного узла обмена сообщениями является источник вызывающего объекта, обычно chrome-extension://[ID of allowed extension]. Это позволяет узлам собственного обмена сообщениями идентифицировать источник сообщения, если в allowed_origins ключе в манифесте собственного узла обмена сообщениями указано несколько расширений. См. раздел Шаг 2. Создание собственного файла манифеста узла обмена сообщениями выше.

В Windows собственный узел обмена сообщениями также передает аргумент командной строки с дескриптором в вызывающее собственное окно Microsoft Edge: --parent-window=<decimal handle value>. Это позволяет собственному узлу обмена сообщениями создавать собственные окна пользовательского интерфейса, которые правильно родительские. Это значение будет равно 0, если контекст вызова является рабочей ролью службы.

Когда порт обмена сообщениями создается с помощью runtime.connectNative, Microsoft Edge запускает собственный процесс узла обмена сообщениями и сохраняет его работу до тех пор, пока порт не будет уничтожен. С другой стороны, когда сообщение отправляется с помощью runtime.sendNativeMessage, без создания порта обмена сообщениями, Microsoft Edge запускает новый собственный процесс узла обмена сообщениями для каждого сообщения. В этом случае первое сообщение, созданное ведущим процессом, обрабатывается как ответ на исходный запрос, и Microsoft Edge передает его обратному вызову ответа, указанному при runtime.sendNativeMessage вызове. Все остальные сообщения, созданные собственным узлом обмена сообщениями в этом случае, игнорируются.

Подключение к собственному приложению

Отправка и получение сообщений в собственное приложение и из нее очень похожа на обмен сообщениями между расширениями. Разница main заключается в том, что 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: Убедитесь, что для режима ввода-вывода программы задано значение O_BINARY. По умолчанию режимом ввода-вывода является O_TEXT, который повреждает формат сообщения, так как разрывы строк (0A = \n) заменяются окончаниями строк в стиле Windows ().\r\n = 0D 0A Режим ввода-вывода можно задать с помощью __setmode.

Примечание.

Части этой страницы являются изменениями, основанными на работе, созданной и совместно используемой Google и используемой в соответствии с условиями, описанными в международной лицензии Creative Commons Attribution 4.0. Исходная страница находится здесь.

Эта работа лицензируется по международной лицензии Creative Commons Attribution 4.0.