Desinstalar suplementos em desenvolvimento

Suplementos removidos incompletamente podem deixar artefatos em seu computador, como botões de faixa de opções personalizados ou entradas do Registro, durante o desenvolvimento. Neste artigo, chamamos isso de "suplementos fantasmas".

Os suplementos do Outlook também podem deixar artefatos em outros computadores quando você entrar no Outlook com a mesma ID usada durante o desenvolvimento.

Importante

Quando você entra no Outlook, ele baixa do Exchange e faz sideload de todos os manifestos do suplemento do Outlook associados à sua ID, incluindo suplementos que você está desenvolvendo em um computador diferente usando a mesma ID. Por exemplo, todos os botões de faixa de opções personalizados definidos no manifesto serão exibidos para o suplemento.

Se as URLs no manifesto apontarem para um servidor que não seja localhost e esse servidor estiver em execução e acessível ao computador que não seja de desenvolvimento, o Outlook armazenará em cache os arquivos do suplemento no sistema de arquivos local e o suplemento geralmente será executado normalmente no computador. Caso contrário, o suplemento não funcionará, mas serão exibidas partes visíveis dele, como botões personalizados da faixa de opções. Eles têm os rótulos definidos no manifesto. Os ícones de botão do suplemento também aparecem se eles já foram armazenados em cache localmente no computador que não é de desenvolvimento e o cache nunca foi limpo. Os arquivos de ícone não são armazenados com o Exchange, portanto, se eles nunca foram armazenados em cache no computador que não é de desenvolvimento (ou o cache foi limpo), os botões têm ícones padrão.

Até que o registro do suplemento seja removido do Exchange, o suplemento continuará aparecendo. Consulte Remover um suplemento fantasma para obter informações sobre como remover o registro no Exchange.

Este artigo fornece algumas orientações para minimizar a chance desses problemas e para resolve-los se ocorrerem.

Evite os problemas

Quando um suplemento é sideload, várias coisas acontecem:

  • Um servidor Web, geralmente no host local, é iniciado para servir os arquivos do suplemento (como os arquivos HTML, CSS e JavaScript).
  • Esses mesmos arquivos são armazenados em cache no computador de desenvolvimento.
  • O suplemento é registrado no computador de desenvolvimento. O registro é feito com entradas do Registro em um computador Windows ou com determinados arquivos salvos no sistema de arquivos em um Mac.
  • A maioria das ferramentas de sideload de suplementos abre automaticamente o aplicativo do Office de destino do suplemento. As ferramentas também preenchem o aplicativo com quaisquer botões de faixa de opções personalizados ou itens do menu de contexto definidos no manifesto do suplemento.
  • Para um suplemento do Outlook, o manifesto do suplemento é registrado no serviço do Exchange.

Usar o recurso de desinstalação da ferramenta

Para evitar suplementos fantasmas, termine todas as sessões de teste, depuração e sideload usando a opção de desinstalação (também chamada de não adquirir) fornecida pela ferramenta que você usou para iniciar a sessão. Isso reverte os efeitos do sideload, conforme declarado anteriormente neste artigo.

A lista a seguir identifica, para cada ferramenta, como desinstalar, mas não descreve os procedimentos ou a sintaxe em detalhes. Certifique-se de usar os links para obter instruções completas.

Observação

Algumas dessas ferramentas não fecham o aplicativo do Office que foi aberto automaticamente. Nesse caso, feche o aplicativo manualmente imediatamente após encerrar a sessão.

  • Gerador Yeoman para Suplementos do Office (Yo Office): Use o npm stop script na mesma linha de comando em que você iniciou a sessão com npm start. Para obter mais informações, consulte os vários artigos nas seções Introdução e Início rápido e Remover um suplemento com sideload.
  • Microsoft 365 Agents Toolkit para Visual Studio Code: selecione Executar | Parar Depuração no Visual Studio Code. Para obter mais informações, consulte a última etapa de Criar um projeto de suplemento do Outlook, que também se aplica a suplementos que não são do Outlook.
  • office-addin-debugging tool: Use o office-addin-debugging stop comando na mesma linha de comando em que você iniciou a sessão com office-addin-debugging start. Para obter mais informações, consulte Fazer sideload com a ferramenta Office-Addin-Debugging.
  • Microsoft 365 Agents Toolkit CLI: Use o atk uninstall comando na mesma linha de comando em que você iniciou a sessão com atk install. Para obter mais informações, consulte Sideload com o Microsoft 365 Agents Toolkit CLI.
  • Visual Studio: selecione DEPURAR | Parar depuração no menu, pressione Shift+F5 ou clique no botão quadrado vermelho "parar" na barra de depuração. Como alternativa, fechar o aplicativo do Office também interrompe a sessão e desinstala o suplemento. Para obter mais informações, consulte Primeiro olhar para o depurador do Visual Studio.

Remover um suplemento fantasma

Para remover um suplemento fantasma, você precisa remover os artefatos que foram criados quando ele foi carregado pela última vez, remover seu registro local e, para suplementos do Outlook, remover seu registro no Exchange.

Dica

Há uma maneira rápida de remover um complemento fantasma em computadores Windows se o suplemento foi instalado com a CLI do Kit de Ferramentas do Teams ou a CLI do Kit de Ferramentas de Agentes. Tente isso primeiro e, se funcionar, você pode ignorar o restante desta seção.

  1. Obtenha a ID do título do suplemento na chave do Registro HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Wef\Developer\OutlookSideloadManifestPath\TitleId. (A cadeia de caracteres "Outlook" está no nome da chave por motivos históricos, mas se aplica a qualquer suplemento instalado com a CLI do Agents Toolkit.)

  2. Execute o seguinte comando em um prompt de comando, bash shell ou terminal. Substitua "{title ID}" pela ID do título do suplemento, incluindo o prefixo "U_"; Por exemplo, U_90d141c6-cf4f-40ee-b714-9df9ea593f39.

    atk uninstall --mode title-id --title-id {title ID} --interactive false

O processo de remoção do suplemento varia, dependendo se o suplemento é para o Outlook ou algum outro aplicativo do Office.

Observação

No manifesto unificado do Microsoft 365, um suplemento pode ser configurado para oferecer suporte ao Outlook e a um ou mais outros aplicativos do Office; ou seja, há mais de um membro da "extensions.requirements.scopes" matriz no manifesto e um dos membros está "mail" (ou a "extensions.requirements.scopes" propriedade não está presente). Trate um suplemento configurado dessa maneira como um suplemento do Outlook.

Se o suplemento fantasma não for um suplemento do Outlook, pule para a seção Remover os artefatos do suplemento.

Remover o registro do Exchange de um suplemento fantasma do Outlook

  1. Entre no Outlook com a mesma ID usada para fazer o sideload do suplemento.

  2. Abra o PowerShell como administrador.

  3. Execute os comandos a seguir. Responda "Sim" a todos os prompts de confirmação.

    Install-Module -Name ExchangeOnlineManagement -RequiredVersion 3.4.0

    Set-ExecutionPolicy RemoteSigned

    Connect-ExchangeOnline

    Observação

    Se o Connect-ExchangeOnline comando retornar o erro "O controle ActiveX '8856f961-340a-11d0-a96b-00c04fd705a2' não pode ser instanciado porque o thread atual não está em um apartamento de thread único", basta executar o comando uma segunda vez. Este é um bug bem conhecido.

  4. Execute o seguinte comando: Responda "Sim" a todos os prompts de confirmação.

    Get-App | Format-Table -Auto DisplayName,AppId

    Uma lista dos suplementos instalados no Outlook é exibida. Isso incluirá suplementos internos da Microsoft e os suplementos que você instalou. Todos os suplementos fantasmas do Outlook também serão listados.

  5. Localize o suplemento fantasma na lista. Se ele foi criado com o Yo Office ou outra ferramenta da Microsoft, ele provavelmente tem o nome "Suplemento do Painel de Tarefas da Contoso".

  6. Copie a ID do aplicativo (um GUID) do suplemento. Você precisará dele para etapas posteriores.

  7. Execute o comando Remove-App -Identity {{The GUID OF YOUR ADD-IN HERE}} (por exemplo, Remove-App -Identity 26ead0cb-10dd-4ba2-86c6-4db111876652). Esse comando remove o suplemento do Exchange.

    Aviso

    A remoção do registro precisa se propagar para todos os servidores Exchange. Aguarde pelo menos três horas antes de prosseguir para a próxima etapa.

  8. Continue com a seção Remover os artefatos do suplemento.

Remover os artefatos do suplemento

Importante

Execute esse procedimento em todos os dispositivos nos quais você teve o sideload do suplemento.

  1. Saia de todos os aplicativos do Office e feche todos eles, incluindo o Outlook.
  2. Limpe o cache do Office. Se o suplemento fantasma der suporte ao Outlook, use Limpar o cache no Outlook manualmente.
  3. Continue com a seção Remover o registro local.

Remover o registro local

Importante

Execute esse procedimento em todos os computadores nos quais você tenha feito sideload no suplemento.

  1. Exclua o registro local do suplemento fantasma. O processo varia dependendo do sistema operacional.

    1. Abra o Editor do Registro.

    2. Navegue até Computer\HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\WEF\Developer. Essa chave lista os suplementos que estão em sideload no momento ou que foram carregados no passado e não foram totalmente desinstalados. O valor Data de cada entrada é o caminho para o manifesto do suplemento. O valor Nome varia dependendo de qual versão de qual ferramenta foi usada para criar e fazer o sideload do suplemento. Se Visual Studio foi usado, o nome normalmente também é o caminho para o manifesto. Para outras ferramentas, o nome normalmente é a ID do suplemento. Quando um aplicativo do Office é iniciado, ele recarrega todos os suplementos listados nessa chave (que oferecem suporte ao aplicativo do Office). O recarregamento pode não ter efeito prático ou perceptível se os artefatos do suplemento tiverem sido excluídos do cache, o manifesto não existir mais no caminho ou os arquivos do suplemento não estiverem sendo atendidos por um servidor.

      Localize a entrada do suplemento fantasma e exclua-a. Se for um suplemento do Outlook, você terá a ID de remoção do registro do Exchange. Você também pode usar o caminho na coluna Dados para localizar o manifesto para ajudar a identificar o suplemento ao qual a entrada se refere e ler a ID do manifesto. Se algum manifesto listado na coluna Dados não existir mais no caminho especificado, exclua as entradas desses manifestos.

      O registro do Windows para a chave chamada Computer\HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\WEF\Developer.

    3. Expanda o ... Nó do desenvolvedor na árvore do Registro. Procure uma subchave cujo nome seja a mesma ID do suplemento fantasma. Se estiver lá, exclua-o.

      O Registro do Windows para a chave chamada Computer\HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\WEF\Developer expandido para mostrar subchaves.

    4. Navegue até Computer\HKEY_USERS\{SID}\Software\Microsoft\Office\16.0\WEF\Developer, onde {SID} é o SID do usuário com o qual você estava conectado quando carregou o suplemento e repita as duas etapas anteriores.

    5. Navegue até Computer\HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Common\CustomUIValidationCache. Na coluna Nome , localize todas as entradas que começam com a ID do suplemento (um GUID) e exclua-as. Em seguida, navegue até Computer\HKEY_USERS\{SID}\Software\Microsoft\Office\16.0\Common\CustomUIValidationCache, onde {SID} é o SID do usuário com o qual você estava conectado quando carregou o suplemento e repita o processo.

      O Registro do Windows para a chave chamada Computer\HKEY_USERS\SID\Software\Microsoft\Office\16.0\Common\CustomUIValidationCache**, onde SID é o SID de um usuário.

  1. Se você estiver removendo um suplemento do Outlook, continue com a seção Teste para remoção de suplementos do Outlook.

Teste para remoção de suplementos do Outlook

Abra o Outlook com a mesma identidade que você usou quando criou o suplemento. Se os artefatos do suplemento (como botões personalizados da faixa de opções) reaparecerem após alguns minutos ou se os manipuladores de eventos do suplemento parecerem estar ativos, a remoção do registro do suplemento do Exchange não se propagou para todos os servidores Exchange. Aguarde pelo menos três horas e repita os procedimentos nas seções Remover os artefatos do suplemento e Remova o registro local no computador em que você observou os artefatos.

Veja também

  • Last updated on