Устранение неполадок при активации контекстных надстроек Outlook

Активация контекстной надстройки Outlook основана на правилах активации в XML-манифесте надстройки. Если условия для выбранного элемента соответствуют правилам активации надстройки, приложение активирует и отображает кнопку надстройки в пользовательском интерфейсе Outlook (область выбора надстройки для создания надстроек, панель надстроек для чтения). Если надстройка не активируется должным образом, возможные причины могут быть связаны с указанными ниже факторами.

Важно!

Контекстные надстройки Outlook на основе сущностей будут прекращены во 2-м квартале 2024 г. Работа по прекращению использования этой функции начнется в мае и продолжится до конца июня. После июня контекстные надстройки больше не смогут обнаруживать сущности в почтовых элементах для выполнения задач над ними. Следующие API также будут прекращены.

• Office.context.mailbox.item.getEntities()
• Office.context.mailbox.item.getEntitiesByType(entityType)
• Office.context.mailbox.item.getFilteredEntitiesByName(name)
• Office.context.mailbox.item.getSelectedEntities()

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

• Разрабатывается альтернативная реализация кнопки "Присоединиться к собранию ", которая активируется надстройками собраний по сети. После завершения поддержки контекстных надстроек на основе сущностей надстройки собраний по сети автоматически переходят на альтернативную реализацию для активации кнопки Присоединиться к собранию .
• Правила регулярных выражений будут поддерживаться после прекращения использования контекстных надстроек на основе сущностей. Мы рекомендуем обновить контекстную надстройку, чтобы использовать правила регулярных выражений в качестве альтернативного решения. Инструкции по реализации этих правил см. в статье Использование правил активации регулярных выражений для отображения надстройки Outlook.

Дополнительные сведения см. в разделе Прекращение использования контекстных надстроек Outlook на основе сущностей.

Является ли почтовый ящик пользователя версией Exchange Server, которая является по крайней мере Exchange 2016?

Во-первых, убедитесь, что учетная запись электронной почты пользователя, которую вы тестируете, находится в версии Exchange Server, которая не менее Exchange 2016. Если вы используете определенные функции, выпущенные после Exchange 2016, убедитесь, что учетная запись пользователя установлена в соответствующей версии Exchange.

Вы можете проверить версию Exchange, используя один из следующих подходов.

• Уточнить у администратора Exchange Server.

• Если вы тестируете надстройку на Outlook в Интернете или мобильных устройствах, в отладчике скриптов (например, в отладчике JScript, который поставляется с интернет-Обозреватель), найдите атрибут srcтега скрипта, который указывает расположение, из которого загружаются скрипты. Путь должен содержать подстроку owa/15.0.516.x/owa2/..., где 15.0.516.x представляет версию Exchange Server, например 15.0.516.2.

• Кроме того, вы можете проверить версию с помощью свойства Office.context.mailbox.diagnostics.hostVersion. В Outlook в Интернете, на мобильных устройствах и в новом Outlook в Windows (предварительная версия) это свойство возвращает версию Exchange Server.

• Если вы можете протестировать надстройку в Outlook, можно использовать следующий простой метод отладки, использующий объектную модель Outlook и Редактор Visual Basic.

  1. Убедиться, что для Outlook включена поддержка макросов. Последовательно выбрать в меню пункты Файл, Параметры, Центр управления безопасностью, Параметры центра управления безопасностью и Параметры макросов. Убедиться, что в центре управления безопасностью установлен флажок Уведомления для всех макросов. При запуске Outlook также должен быть установлен флажок Включить макросы.

  2. На вкладке Разработчик ленты выберите Visual Basic.

     Примечание.

     Не видите вкладку "Разработчик" ? See How to: Show the Developer Tab on the Ribbon to turn it on.

  3. В редакторе Visual Basic выберите Вид > Окно интерпретации.

  4. Type the following in the Immediate window to display the version of the Exchange Server. The major version of the returned value must be equal to or greater than 15.

     • Если в профиле пользователя только одна учетная запись Exchange:

      ?Session.ExchangeMailboxServerVersion
     

     • Если в профиле пользователя несколько учетных записей Exchange (emailAddress представляет строку, содержащую основной SMTP-адрес пользователя):

      ?Session.Accounts.Item(emailAddress).ExchangeMailboxServerVersion
     

Доступна ли надстройка?

Outlook в Windows и на Mac может сделать надстройку недоступной из-за соображений производительности, включая превышение пороговых значений использования ядра ЦП или памяти, допустимость сбоев и продолжительность обработки всех регулярных выражений для надстройки. В этом случае Outlook в Windows и mac отображает уведомление о том, что надстройка недоступна.

Примечание.

Только классические Outlook в Windows и Outlook на Mac отслеживают использование ресурсов. Однако надстройка, сделанная недоступной в классической версии Outlook в Windows или Outlook на Mac, также становится недоступной в Outlook в Интернете, на мобильных устройствах и в новой версии Outlook в Windows (предварительная версия).

Проверьте список установленных надстроек, чтобы проверить, доступна ли надстройка. Инструкции по просмотру надстроек в Outlook см. в статье Использование надстроек в Outlook.

Поддерживает ли тестируемый элемент надстройки Outlook? Поставляется ли выбранный элемент версией Exchange Server по крайней мере Exchange 2016?

Если ваша надстройка Outlook является надстройкой чтения, которая должна активироваться, когда пользователь просматривает сообщение (включая письма, приглашения на собрания, а также ответы и отмены) или встречу, хотя в целом эти элементы поддерживают надстройки, существуют исключения. Проверьте, является ли выбранный элемент одним из перечисленных, где надстройки Outlook не активируются.

Кроме того, так как встречи всегда сохраняются в формате форматированного текста, правило ItemHasRegularExpressionMatch , указывающее значение PropertyNameэлемента BodyAsHTML , не активирует надстройку для встречи или сообщения, сохраненных в виде обычного текста или формата форматов.

Даже если почтовый элемент не относится к одному из указанных выше типов, если он не был доставлен версией Exchange Server, которая является по крайней мере Exchange 2016, известные сущности и свойства, такие как SMTP-адрес отправителя, не будут определены в элементе. Все правила активации, основанные на этих сущностях или свойствах, не будут удовлетворены, и надстройка не будет активирована.

Установлен ли манифест надстройки должным образом, и есть ли Outlook кэшированная копия?

Примечание.

Функции надстроек Outlook, зависящие от правил активации, не поддерживаются, если надстройка использует унифицированный манифест для Microsoft 365.

Этот сценарий применяется только к Outlook в Windows. Обычно при установке надстройки Outlook для почтового ящика Exchange Server копирует манифест надстройки из указанного вами расположения в почтовый ящик в Exchange Server. При каждом запуске Outlook он считывает все манифесты, установленные для этого почтового ящика, во временный кэш в следующем расположении.

%LocalAppData%\Microsoft\Office\16.0\WEF

Например, для пользователя John кэш может находиться в папке C:\Users\john\AppData\Local\Microsoft\Office\16.0\WEF.

Если надстройка не активируется для каких-либо элементов, возможно, манифест был неправильно установлен на Exchange Server или Outlook неправильно считывает манифест при запуске. С помощью Центра администрирования Exchange убедитесь, что надстройка установлена и включена для этого почтового ящика, и при необходимости перезагрузите Exchange Server.

На следующем рисунке показана сводка действий по проверке наличия в Outlook допустимой версии манифеста.

В следующей процедуре подробно описываются эти действия.

1. Если вы изменили манифест во время открытия Outlook и не используете Visual Studio 2015 или более поздней версии Visual Studio для разработки надстройки, удалите надстройку и переустановите ее с помощью Центра Администратор Exchange.

2. Перезапустите Outlook и проверьте, активирует ли Outlook надстройку теперь.

3. Если Outlook не активирует надстройку, проверьте, есть ли у Outlook кэшированная копия манифеста надстройки. Просмотрите следующий путь.

   %LocalAppData%\Microsoft\Office\16.0\WEF
   

   Манифест можно найти в следующей вложенной папке.

   \<insert your guid>\<insert base 64 hash>\Manifests\<ManifestID>_<ManifestVersion>
   

   Примечание.

   Ниже приведен пример пути к манифесту, установленному для почтового ящика пользователя John.

   C:\Users\john\appdata\Local\Microsoft\Office\16.0\WEF\{8D8445A4-80E4-4D6B-B7AC-D4E6AF594E73}\GoRshCWa7vW8+jhKmyiDhA==\Manifests\b3d7d9d5-6f57-437d-9830-94e2aaccef16_1.2
   

   Проверьте, есть ли манифест тестируемой надстройки в кэше.

4. Если манифест есть в кэше, пропустите остальную часть этого раздела и рассмотрите другие возможные причины ниже.

5. Если манифест в кэше отсутствует, проверьте, действительно ли Outlook успешно считал этот манифест в Exchange Server. Для этого воспользуйтесь средством просмотра событий Windows.

   1. В разделе Журналы Windows выберите Приложение.

   2. Найдите достаточно недавнее событие, идентификатор которого равен 63, что представляет загрузку Outlook манифеста из Exchange Server.

   3. Если Outlook успешно считывает манифест, зарегистрированное событие должно иметь следующее описание.

      The Exchange web service request GetAppManifests succeeded.
      

      В этом случае пропустите остальную часть этого раздела и рассмотрите другие возможные причины ниже.

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

   %LocalAppData%\Microsoft\Office\16.0\WEF\<insert your guid>\<insert base 64 hash>\Manifests\
   

   Запустите Outlook и проверьте, активирует ли Outlook надстройку.

7. Если Outlook по-прежнему не активирует надстройку, вернитесь к шагу 3 и еще раз проверьте, прочитал ли Outlook манифест.

Действителен ли манифест надстройки?

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

Используются ли необходимые правила активации?

Начиная с версии 1.1 схемы манифестов надстроек Office можно создавать надстройки, которые активируются, когда пользователь находится в форме создания (создание надстроек) или в форме чтения (надстройки чтения). Убедитесь, что вы указали соответствующие правила активации для каждого типа формы, в которых должна активироваться надстройка. Например, можно активировать надстройки создания, используя только правила ItemIs с атрибутом FormType , для которого задано значение Edit или ReadOrEdit, и нельзя использовать правила других типов, таких как ItemHasKnownEntity и ItemHasRegularExpressionMatch для надстроек создания. Дополнительные сведения см . в разделе Правила активации для надстроек Outlook.

Если используется регулярное выражение, указано ли оно должным образом?

Поскольку регулярные выражения в правилах активации являются частью XML-файла манифеста надстройки чтения, при использовании в регулярных выражениях определенных символов убедитесь, что используется соответствующая escape-последовательность, которую поддерживают XML-процессоры. Они перечислены в следующей таблице.

Символ	Описание	Используемая escape-последовательность
"	Двойная кавычка	&цитата;
&	Амперсанд	&усилие;
'	Апостроф	'
<	Знак "меньше"	<
>	Знак "больше"	>

Если вы используете регулярное выражение, активируется ли надстройка чтения в Outlook в Интернете, на мобильных устройствах или в новом Outlook в Windows (предварительная версия), но не в классическом Outlook в Windows или Outlook на Mac?

Классические Приложения Outlook в Windows и Outlook на Mac используют механизм регулярных выражений, отличный от механизма, используемого Outlook в Интернете, на мобильных устройствах и в новых приложениях Outlook для Windows (предварительная версия). Классические Outlook в Windows и Outlook на Mac используют обработчик регулярных выражений C++, предоставляемый в стандартной библиотеке шаблонов Visual Studio. Этот обработчик выполняет компиляцию в соответствии со стандартами ECMAScript 5. Outlook в Интернете, на мобильных устройствах и в новом Outlook в Windows (предварительная версия) используют оценку регулярных выражений, которая является частью JavaScript, предоставляется браузером и поддерживает надмножество ECMAScript 5.

Хотя в большинстве случаев эти клиенты Outlook находят одинаковые совпадения для одного регулярного выражения в правиле активации, существуют исключения. Например, если регулярное выражение содержит пользовательский класс символов, основанный на стандартных классах символов, классический Outlook для Windows и Outlook на Mac может возвращать результаты, отличные от Outlook в Интернете, на мобильных устройствах и новых Outlook для Windows (предварительная версия). Например, классы символов, содержащие сокращенные классы символов [\d\w] в них, будут возвращать разные результаты. В этом случае, чтобы избежать разных результатов в разных приложениях, используйте (\d|\w) вместо этого.

Тщательно проверьте регулярное выражение. Если оно возвращает разные результаты, то переделайте его, чтобы оно было совместимо с обоими модулями. Чтобы проверить результаты оценки в классическом Outlook для Windows и Outlook на Mac, напишите небольшую программу C++, которая применяет регулярное выражение к образцу текста, который вы пытаетесь сопоставить. Запущенная в Visual Studio тестовая программа C++ будет использовать стандартную библиотеку шаблонов, имитируя поведение классического Outlook в Windows или Outlook на Mac при выполнении одного регулярного выражения. Чтобы проверить результаты оценки в Outlook в Интернете, на мобильных устройствах и в новом Outlook в Windows (предварительная версия), используйте свой любимый тестировщик регулярных выражений JavaScript.

Если используется правило ItemIs, ItemHasAttachment или ItemHasRegularExpressionMatch, проверено ли соответствующее свойство элемента?

Если вы используете правило активации ItemHasRegularExpressionMatch, проверьте, соответствует ли значение атрибута PropertyName предполагаемому значению для выбранного элемента. Ниже приведены некоторые советы по отладке соответствующих свойств.

• Если выбранный элемент представляет собой сообщение, и в атрибуте PropertyName вы указываете значение BodyAsHTML, откройте это сообщение и выберите Просмотреть код, чтобы проверить текст сообщения в HTML-представлении этого элемента.

• Если выбранный элемент представляет собой встречу или если правило активации задает BodyAsPlaintext в атрибуте PropertyName, вы можете использовать объектную модель Outlook и редактор Visual Basic в Outlook для Windows.

  1. Убедитесь, что макросы включены и на ленте Outlook отображается вкладка Разработчик .

  2. В редакторе Visual Basic выберите Вид > Окно интерпретации.

  3. Для отображения разных свойств в зависимости от сценария введите следующее.

     • Для HTML-текста элемента сообщения или встречи, выбранного в обозревателе Outlook:

     ?ActiveExplorer.Selection.Item(1).HTMLBody
     

     • Для простого текста элемента сообщения или встречи, выбранного в обозревателе Outlook:

     ?ActiveExplorer.Selection.Item(1).Body
     

     • Для HTML-текста элемента сообщения или встречи, выбранного в инспекторе Outlook:

     ?ActiveInspector.CurrentItem.HTMLBody
     

     • Для простого текста элемента сообщения или встречи, выбранного в инспекторе Outlook:

     ?ActiveInspector.CurrentItem.Body
     

Если правило активации ItemHasRegularExpressionMatch указывает Subject или SenderSMTPAddress, или если вы используете правило ItemIs или ItemHasAttachment и знакомы с MAPI или хотите использовать MAPI, используйте MFCMAPI. Проверьте свойство MAPI, на которое опирается правило, в следующей таблице.

Тип правила	Свойство MAPI для проверки
Правило ItemHasRegularExpressionMatch с Subject	PidTagSubject
Правило ItemHasRegularExpressionMatch с SenderSMTPAddress	PidTagSenderSmtpAddress и PidTagSentRepresentingSmtpAddress
ItemIs	PidTagMessageClass
ItemHasAttachment	PidTagHasAttachments

После проверки значения свойства можно с помощью средства оценки регулярных выражений проверить, находит ли регулярное выражение соответствие в этом значении.

Применяет ли Outlook все регулярные выражения к части текста элемента, как вы ожидаете?

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

• Вычислимый размер текста элемента. Существуют ограничения на часть текста элемента, на которой Outlook вычисляет регулярное выражение. Эти ограничения зависят от клиента Outlook, форм-фактора и формата текста элемента. Дополнительные сведения см. в разделе Ограничения на размер вычисляемого текста элемента.

• Количество совпадений регулярных выражений. Outlook в Windows (классическая и новая (предварительная версия)), на Mac, в Интернете и на мобильных устройствах возвращает не более 50 совпадений с регулярными выражениями. Эти совпадения уникальны, и повторяющиеся совпадения не учитываются в этом ограничении. Не предполагайте порядок возвращаемых совпадений и не предполагайте, что порядок в классической версии Outlook в Windows и Outlook на Mac совпадает с порядком в Outlook в Интернете, на мобильных устройствах и в новой версии Outlook в Windows (предварительная версия). Если вы ожидаете много соответствий регулярным выражениям в правилах активации, и какое-либо соответствие пропускается, то, возможно, было превышено это ограничение.

• Длина совпадения регулярного выражения. Существуют ограничения на длину совпадения регулярного выражения, возвращаемого приложением Outlook. Outlook не содержит совпадений, превышающих ограничение, и не отображает предупреждающее сообщение. Вы можете проверить ваше регулярное выражение с помощью других средств оценки регулярных выражений или автономной тестовой программы на C++, чтобы проверить, имеются ли соответствия, превышающие ограничения. В следующей таблице перечислены ограничения. Дополнительные сведения см. в разделе Ограничения правил активации для контекстной надстройки Outlook.

  Ограничение длины для результата, соответствующего регулярному выражению	Outlook в Интернете, на мобильных устройствах и в новом клиенте Windows (предварительная версия)	Outlook в классическом клиенте Windows и на Mac
  Основной текст элемента в виде простого текста	3 КБ	1,5 КБ
  Основной текст элемента в виде HTML-кода	3 КБ	3 КБ

• Время, затраченное на оценку всех регулярных выражений надстройки чтения в классической версии Outlook в Windows и Outlook на Mac. По умолчанию для каждой надстройки чтения Outlook должен завершить оценку всех регулярных выражений в правилах активации в течение одной секунды. В противном случае Outlook повторяет до трех раз и делает надстройку недоступной, если Outlook не может завершить оценку. Outlook отображает на панели уведомлений сообщение о том, что надстройка недоступна. Время, доступное для регулярного выражения, можно изменить, задав групповую политику или раздел реестра.

  Примечание.

  Если классическая версия Outlook в Windows или Outlook на Mac делает надстройку для чтения недоступной, надстройка чтения становится недоступной в том же почтовом ящике в Outlook в Интернете, на мобильных устройствах и в новом Outlook для Windows (предварительная версия).

См. также

• Развертывание и установка надстроек Outlook для тестирования
• Правила активации для надстроек Outlook
• Использование правил активации на основе регулярных выражений для отображения надстройки Outlook
• Ограничения для активации и API JavaScript для надстроек Outlook
• Проверка манифеста и устранение связанных с ним неполадок