Solução de problemas de ativação de suplementos contextuais do Outlook

  • Artigo

A ativação de suplemento contextual do Outlook baseia-se nas regras de ativação em um manifesto XML para o suplemento. Quando as condições do item selecionado atualmente atendem às regras de ativação do suplemento, o aplicativo ativa e exibe o botão de suplemento na interface do usuário do Outlook (painel de seleção de suplementos para suplementos de composição, barra de suplementos para suplementos de leitura). No entanto, se seu suplemento não for ativado conforme o esperado, procure a causa nas áreas a seguir.

Importante

Os suplementos contextuais do Outlook baseados em entidade serão desativados no segundo trimestre de 2024. O trabalho para aposentar esse recurso começará em maio e continuará até o final de junho. Após junho, os suplementos contextuais não poderão mais detectar entidades em itens de email para executar tarefas neles. As APIs a seguir também serão retiradas.

Para ajudar a minimizar possíveis interrupções, o seguinte ainda será suportado depois que os suplementos contextuais baseados em entidade forem retirados.

  • Uma implementação alternativa do botão Ingressar Reunião , que é ativado por suplementos de reunião online, está sendo desenvolvida. Depois que o suporte para suplementos contextuais baseados em entidade terminar, os suplementos de reunião online farão a transição automática para a implementação alternativa para ativar o botão Ingressar Reunião .
  • As regras de expressão regular continuarão a ser suportadas depois que os suplementos contextuais baseados em entidade forem retirados. Recomendamos atualizar seu suplemento contextual para usar regras de expressão regulares como uma solução alternativa. Para obter diretrizes sobre como implementar essas regras, consulte Usar regras regulares de ativação de expressão para mostrar um suplemento do Outlook.

Para obter mais informações, consulte Aposentadoria de suplementos contextuais do Outlook baseados em entidade.

A caixa de correio do usuário está em uma versão de Exchange Server que é pelo menos o Exchange 2016?

Primeiro, verifique se a conta de email do usuário com a qual você está testando está em uma versão do Exchange Server que é pelo menos o Exchange 2016. Se você estiver usando recursos específicos que são lançados após o Exchange 2016, verifique se a conta do usuário está na versão apropriada do Exchange.

Você pode verificar a versão do Exchange usando uma das abordagens a seguir.

  • Verifique com o administrador do Exchange Server.

  • Se você estiver testando o suplemento em dispositivos Outlook na Web ou móveis, em um depurador de script (por exemplo, o Depurador JScript que vem com a Internet Explorer), procure o atributo src da marca de script que especifica o local do qual os scripts são carregados. O caminho deve conter uma substring owa/15.0.516.x/owa2/..., em que 15.0.516.x representa a versão do Exchange Server, como 15.0.516.2.

  • Como alternativa, você pode usar a propriedade Office.context.mailbox.diagnostics.hostVersion para verificar a versão. Em Outlook na Web, em dispositivos móveis e no novo Outlook no Windows (versão prévia), essa propriedade retorna a versão do Exchange Server.

  • Se você puder testar o suplemento no Outlook, poderá usar a seguinte técnica de depuração simples que usa o modelo de objeto do Outlook e o Visual Basic Editor.

    1. Primeiro, verifique se as macros estão habilitadas para o Outlook. Escolha Arquivo, Opções, Centro de Confiança, Configurações do Centro de Confiança, Configurações de Macro. Verifique se as notificações para todas as macros estão selecionadas na Central de Confiança. Você deve escolher também Habilitar Macros, durante a inicialização do Outlook.

    2. Na guia Desenvolvedor da faixa de opções, escolha Visual Basic.

      Observação

      Não está vendo a guia Desenvolvedor ? See How to: Show the Developer Tab on the Ribbon to turn it on.

    3. No Editor do Visual Basic, escolha Exibir, Janela Imediata.

    4. Digite o texto a seguir na janela Imediata para exibir a versão do Exchange Server. A versão principal do valor retornado deve ser igual ou maior que 15.

      • Se houver apenas uma conta do Exchange no perfil do usuário:
       ?Session.ExchangeMailboxServerVersion
      • Caso haja várias contas do Exchange no mesmo perfil de usuário (emailAddress representa uma cadeia de caracteres que contém o endereço SMTP principal do usuário):
       ?Session.Accounts.Item(emailAddress).ExchangeMailboxServerVersion

O suplemento está disponível?

O Outlook no Windows e no Mac pode tornar um suplemento indisponível devido a motivos de desempenho, incluindo exceder limites de uso para o núcleo ou memória da CPU, tolerância a falhas e tempo para processar todas as expressões regulares para um suplemento. Quando isso acontece, o Outlook no Windows e no Mac exibe uma notificação de que está tornando um suplemento indisponível.

Observação

Somente o Outlook clássico no Windows e no Outlook no uso de recursos do Mac Monitor. No entanto, um suplemento indisponível no Outlook clássico no Windows ou no Outlook no Mac também fica indisponível em Outlook na Web, em dispositivos móveis e no novo Outlook no Windows (versão prévia).

Verifique sua lista de suplementos instalados para verificar se um suplemento está disponível. Para obter instruções sobre como exibir seus suplementos no Outlook, consulte Usar suplementos no Outlook.

O item testado dá suporte a suplementos do Outlook? O item selecionado é entregue por uma versão do Exchange Server que é pelo menos o Exchange 2016?

Se o seu suplemento do Outlook é um suplemento de leitura e deve ser ativado quando o usuário está exibindo uma mensagem (inclusive mensagens de email, solicitações de reunião, respostas e cancelamentos de reunião) ou um compromisso, embora esses itens geralmente sejam compatíveis com suplementos, há exceções. Verifique se o item selecionado é um dos listados em que os suplementos do Outlook não são ativados.

Além disso, como os compromissos são sempre salvos no Rich Text Format, uma regra ItemHasRegularExpressionMatch que especifica um valor PropertyName de BodyAsHTML não ativaria um suplemento em um compromisso ou mensagem salva em texto simples ou Formato de Texto Rico.

Mesmo que um item de email não seja um dos tipos acima, se o item não tiver sido entregue por uma versão de Exchange Server pelo menos o Exchange 2016, entidades e propriedades conhecidas, como o endereço SMTP do remetente, não seriam identificados no item. Todas as regras de ativação que dependem dessas entidades ou propriedades não seriam atendidas e o suplemento não seria ativado.

O manifesto do suplemento está instalado corretamente? O Outlook tem uma cópia armazenada em cache?

Observação

Não há suporte para recursos de suplemento do Outlook que dependem de regras de ativação quando o suplemento usa um manifesto unificado para o Microsoft 365.

Esse cenário se aplica apenas ao Outlook no Windows. Normalmente, quando você instala um suplemento do Outlook para uma caixa de correio, o Exchange Server copia manifesto do suplemento do local indicado para a caixa de correio nesse Exchange Server. Sempre que o Outlook é iniciado, ele lê todos os manifestos instalados para essa caixa de correio em um cache temporário no local a seguir.

%LocalAppData%\Microsoft\Office\16.0\WEF

Por exemplo, para o usuário John, o cache pode estar em C:\Users\john\AppData\Local\Microsoft\Office\16.0\WEF.

Se um suplemento não for ativado para nenhum item, o manifesto poderá não ter sido instalado corretamente no Exchange Server ou o Outlook não leu o manifesto corretamente na inicialização. Usando o Centro de Administração do Exchange, verifique se o suplemento está instalado e habilitado para sua caixa de correio e reinicie o Exchange Server, se necessário.

A figura a seguir mostra um resumo das etapas para verificar se o Outlook tem uma versão válida do manifesto.

Fluxograma para marcar manifesto.

O procedimento a seguir descreve os detalhes.

  1. Se você tiver modificado o manifesto enquanto o Outlook estiver aberto e não estiver usando o Visual Studio 2015 ou uma versão posterior do Visual Studio para desenvolver o suplemento, desinstale o suplemento e reinstale-o usando o Exchange Administração Center.

  2. Reinicie o Outlook e teste se ele agora ativa o suplemento.

  3. Se o Outlook não ativar o suplemento, verifique se tem uma cópia corretamente armazenada em cache do manifesto para o suplemento. Procure no caminho a seguir.

    %LocalAppData%\Microsoft\Office\16.0\WEF

    Você pode encontrar o manifesto na subpasta a seguir.

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

    Observação

    A seguir está um exemplo de um caminho para um manifesto instalado para uma caixa de correio para o usuário 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

    Verifique se o manifesto do suplemento que você está testando está entre os manifestos armazenados em cache.

  4. Se o manifesto estiver no cache, ignore o restante desta seção e considere outros motivos possíveis após esta seção.

  5. Se o manifesto não estiver no cache, verifique se o Outlook leu o manifesto do Exchange Server com êxito. Para fazer isso, use o Visualizador de Eventos do Windows:

    1. Em Logs do Windows, escolha Aplicativo.

    2. Procure um evento razoavelmente recente com ID de Evento igual a 63, que representa o Outlook baixando um manifesto de um Exchange Server.

    3. Se o Outlook ler com êxito um manifesto, o evento registrado deverá ter a descrição a seguir.

      The Exchange web service request GetAppManifests succeeded.

      Ignore o restante desta seção e considere outros motivos possíveis após esta seção.

  6. Se você não vir um evento bem-sucedido, feche o Outlook e exclua todos os manifestos no caminho a seguir.

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

    Inicie o Outlook e teste se ele agora ativa o suplemento.

  7. Se o Outlook não ativar o suplemento, volte para a etapa 3 e verifique novamente se o Outlook leu o manifesto corretamente.

O manifesto do suplemento é válido?

Confira Validar e solucionar problemas com seu manifesto para depurar problemas do manifesto de suplemento.

Você está usando as regras de ativação apropriadas?

A partir da versão 1.1 do esquema de manifestos de suplementos do Office, você pode criar suplementos que são ativados quando o usuário está em um formulário de composição (suplementos de composição) ou em um formulário de leitura (suplementos de leitura). Especifique as regras de ativação apropriadas para cada tipo de formulário no qual seu suplemento deve ser ativado. Por exemplo, você pode ativar suplementos de composição usando apenas regras ItemIs com o atributo FormType definido como Editar ou ReadOrEdit e não pode usar nenhum dos outros tipos de regras, como ItemHasKnownEntity e ItemHasRegularExpressionMatch para suplementos de composição. Para obter mais informações, confira Regras de ativação para suplementos do Outlook.

Se você está usando uma expressão regular, ela foi especificada corretamente?

Já que as expressões regulares nas regras de ativação fazem parte do arquivo de manifesto XML para um suplemento de leitura, se uma expressão regular usa determinados caracteres, use a sequência de escape correspondente compatível com processadores XML. A tabela a seguir lista os caracteres especiais.

Caractere Descrição Sequência de escape a ser usada
" Aspas duplas &cotação;
& E comercial &
' Apóstrofo '
< Sinal menor que <
> Sinal maior que >

Se você usar uma expressão regular, o suplemento de leitura será ativado em Outlook na Web, em dispositivos móveis ou no novo Outlook no Windows (versão prévia), mas não no Outlook clássico no Windows ou outlook no Mac?

O Outlook clássico no Windows e no Outlook no Mac usa um mecanismo de expressão regular diferente daquele usado por Outlook na Web, em dispositivos móveis e no novo Outlook no Windows (versão prévia). O Outlook clássico no Windows e no Outlook no Mac usa o mecanismo de expressão regular C++ fornecido como parte da biblioteca de modelos padrão do Visual Studio. Esse mecanismo é compatível com as normas ECMAScript 5. Outlook na Web, em dispositivos móveis e novo Outlook no Windows (versão prévia) usam a avaliação de expressão regular que faz parte do JavaScript, é fornecida pelo navegador e dá suporte a um superconjunto de ECMAScript 5.

Embora, na maioria dos casos, esses clientes do Outlook encontrem as mesmas correspondências para a mesma expressão regular em uma regra de ativação, há exceções. Por exemplo, se o regex incluir uma classe de caractere personalizada com base em classes de caracteres predefinidas, o Outlook clássico no Windows e no Outlook no Mac poderá retornar resultados diferentes de Outlook na Web, em dispositivos móveis e novo Outlook no Windows (versão prévia). Como exemplo, classes de caracteres que contêm classes [\d\w] de caracteres abreviadas dentro delas retornariam resultados diferentes. Nesse caso, para evitar resultados diferentes em aplicativos diferentes, use (\d|\w) em vez disso.

Teste sua expressão regular minuciosamente. Se ela retornar resultados diferentes, reescreva a expressão regular para ficar compatível em ambos os mecanismos. Para verificar os resultados da avaliação no Outlook clássico no Windows e no Outlook no Mac, escreva um pequeno programa C++ que aplica a expressão regular em um exemplo do texto que você está tentando corresponder. Em execução no Visual Studio, o programa de teste C++ usaria a biblioteca de modelos padrão, simulando o comportamento do Outlook clássico no Windows ou outlook no Mac ao executar a mesma expressão regular. Para verificar os resultados da avaliação em Outlook na Web, em dispositivos móveis e no novo Outlook no Windows (versão prévia), use o testador de expressão regular JavaScript favorito.

Se você usa uma regra de ativação ItemHasRegularExpressionMatch, verifique se o valor do atributo PropertyName é o que você espera do item selecionado. A seguir estão algumas dicas para depurar as propriedades correspondentes.

  • Se o item selecionado for uma mensagem e especificar BodyAsHTML no atributo PropertyName, abra a mensagem e escolha Exibir Código-fonte para verificar o corpo da mensagem na representação HTML desse item.

  • Se o item selecionado for um compromisso ou se a regra de ativação especificar BodyAsPlaintext no PropertyName, você poderá usar o modelo de objeto do Outlook e o Editor do Visual Basic no Outlook no Windows:

    1. Verifique se as macros estão habilitadas e a guia Desenvolvedor é exibida na faixa de opções do Outlook.

    2. No Editor do Visual Basic, escolha Exibir, Janela Imediata.

    3. Digite o texto a seguir para exibir várias propriedades dependendo do cenário.

      • O corpo HTML do item selecionado de compromisso ou mensagem no Outlook Explorer:
      ?ActiveExplorer.Selection.Item(1).HTMLBody
      • O corpo de texto sem formatação do item selecionado de compromisso ou mensagem no Outlook Explorer:
      ?ActiveExplorer.Selection.Item(1).Body
      • O corpo HTML do item selecionado de compromisso ou mensagem aberto no inspetor atual do Outlook:
      ?ActiveInspector.CurrentItem.HTMLBody
      • O corpo de texto sem formatação do item selecionado de compromisso ou mensagem aberto no inspetor atual do Outlook:
      ?ActiveInspector.CurrentItem.Body

Se a regra de ativação ItemHasRegularExpressionMatchespecificar Assunto ou SenderSMTPAddress ou se você usar uma regra ItemIs ou ItemHasAttachment e estiver familiarizado ou quiser usar MAPI, use MFCMAPI. Verifique a propriedade MAPI na qual sua regra depende na tabela a seguir.

Tipo de regra Verifique essa propriedade MAPI
Regra ItemHasRegularExpressionMatch com Subject PidTagSubject
Regra ItemHasRegularExpressionMatch com SenderSMTPAddress PidTagSenderSmtpAddress e PidTagSentRepresentingSmtpAddress
ItemIs PidTagMessageClass
ItemHasAttachment PidTagHasAttachments

Depois de verificar o valor da propriedade, você pode usar uma ferramenta de avaliação da expressão regular para testar se a expressão regular localiza uma correspondência a esse valor.

O Outlook aplica todas as expressões regulares à parte do corpo do item como você espera?

Esta seção se aplica a todas as regras de ativação que usam expressões regulares, particularmente, aquelas que são aplicadas ao corpo do item, que podem ser grandes em tamanho e demoram mais para serem avaliadas para correspondências. Você deve estar ciente de que, mesmo que a propriedade do item da qual uma regra de ativação dependa tenha o valor esperado, o Outlook pode não ser capaz de avaliar todas as expressões regulares sobre todo o valor da propriedade do item. Para fornecer um desempenho razoável e controlar o uso excessivo de recursos por um suplemento de leitura, o Outlook observa os seguintes limites no processamento de expressões regulares em regras de ativação no runtime.

  • O tamanho do corpo do item avaliado. Há limites para a parte de um corpo de item no qual o Outlook avalia uma expressão regular. Esses limites dependem do cliente do Outlook, do fator de formulário e do formato do corpo do item. Para obter mais informações, consulte Limites no tamanho do corpo do item avaliado.

  • Número de correspondências de expressão regular. O Outlook no Windows (clássico e novo (versão prévia)), no Mac, na Web e em dispositivos móveis, cada um retorna um máximo de 50 correspondências de expressão regulares. Essas correspondências são exclusivas e as correspondências duplicadas não contam com esse limite. Não assuma nenhuma ordem para as correspondências retornadas e não assuma que a ordem no Outlook clássico no Windows e no Outlook no Mac é a mesma que em Outlook na Web, em dispositivos móveis e no novo Outlook no Windows (versão prévia). Se espera muitas correspondências para expressões regulares em suas regras de ativação e está faltando uma correspondência, é possível que você esteja excedendo esse limite.

  • Comprimento de uma correspondência de expressão regular. Há limites para o comprimento de uma expressão regular que o aplicativo Outlook retornaria. O Outlook não inclui nenhuma correspondência acima do limite e não exibe nenhuma mensagem de aviso. Você pode executar sua expressão regular usando outras ferramentas de avaliação de regex ou um programa de teste C++ autônomo para verificar se há uma correspondência que excede esses limites. A tabela a seguir resume os limites. Para obter mais informações, confira Limites de regras de ativação para o suplemento contextual do Outlook.

    Limite de comprimento de uma correspondência de regex Outlook na Web, em dispositivos móveis e em novo cliente Windows (versão prévia) Outlook no cliente clássico do Windows e no Mac
    O corpo do item é texto sem formatação 3 KB 1,5 KB
    Corpo do item é HTML 3 KB 3 KB

  • Tempo gasto na avaliação de todas as expressões regulares de um suplemento de leitura no Outlook clássico no Windows e no Outlook no Mac. Por padrão, para cada suplemento de leitura, o Outlook deve concluir a avaliação de todas as expressões regulares em suas regras de ativação em um segundo. Caso contrário, o Outlook tenta novamente até três vezes e torna o suplemento indisponível se o Outlook não puder concluir a avaliação. O Outlook exibe uma mensagem na barra de notificação de que o suplemento não está disponível. A quantidade de tempo disponível para sua expressão regular pode ser modificada com a definição de uma política de grupo ou uma chave do registro.

    Observação

    Se o Outlook clássico no Windows ou outlook no Mac tornar um suplemento de leitura indisponível, o suplemento de leitura ficará indisponível na mesma caixa de correio em Outlook na Web, em dispositivos móveis e no novo Outlook no Windows (versão prévia).

Confira também