Compartilhar via

Converter um suplemento para usar o manifesto unificado do Microsoft 365

  • Artigo

Para adicionar recursos do Teams a um suplemento que usa o manifesto XML ou apenas à prova futura do suplemento, você precisa convertê-lo para usar o manifesto unificado para o Microsoft 365.

Há três tarefas básicas para converter um projeto de suplemento do manifesto XML no manifesto unificado.

  • Verifique se o suplemento está pronto para ser convertido.
  • Converta o manifesto XML em si no formato JSON do manifesto unificado.
  • Empacotar o novo manifesto e os dois arquivos de imagem de ícone em um arquivo zip para sideload ou implantação.

Observação

Os suplementos do Office que usam o manifesto unificado para o Microsoft 365 têm suporte direto no Office na Web, no novo Outlook no Windows (versão prévia)e no Office no Windows conectado a uma assinatura do Microsoft 365, versão 2304 (Build 16320.00000) ou posterior.

Quando o pacote de aplicativo que contém o manifesto unificado é implantado no AppSource ou no Centro de Administração Microsoft 365, se o manifesto tiver uma propriedade "alternateIcons" válida, um manifesto XML será gerado a partir do manifesto unificado e armazenado. Esse manifesto XML permite que o suplemento seja instalado em plataformas que não dão suporte diretamente ao manifesto unificado, incluindo Office no Mac, Office no celular, versões de assinatura do Office no Windows anteriores a 2304 (Build 16320.00000) e versões perpétuas do Office no Windows.

Observação

  • Os suplementos que usam o manifesto unificado podem ser carregados de lado somente na Versão 2304 do Office (Build 16320.20000) ou posterior.
  • Projetos criados no Visual Studio, diferentemente de Visual Studio Code, não podem ser convertidos no momento.
  • Se você criou o projeto com o Teams Toolkit ou com a opção "manifesto unificado" no Gerador do Office Yeoman, ele já usa o manifesto unificado.

Verifique se o suplemento está pronto para converter

As seções a seguir descrevem as condições que devem ser atendidas antes de converter o manifesto.

Verifique se você tem os dois arquivos de imagem

Quando você tiver adicionado os arquivos ao projeto, adicione <IconUrl> e <HighResolutionIconUrl> (nessa ordem) ao manifesto XML logo abaixo do <elemento Description> . Apresentamos um exemplo a seguir.

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
  <Id>01234567-89ab-cdef-0123-4567-89abcdef0123</Id>
  <Version>1.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-us</DefaultLocale>
  <DisplayName DefaultValue="Great Add-in"/>
  <Description DefaultValue="A great add-in."/>
  <IconUrl DefaultValue="https://localhost:3000/assets/icon-64.png" />
  <HighResolutionIconUrl DefaultValue="https://localhost:300/assets/icon-128.png" />

  <!-- Other markup omitted -->

Verifique se os nomes de comando da função são curtos o suficiente

Se o manifesto tiver elementos <FunctionName> , verifique se os valores deles têm menos de 65 caracteres. O valor desse elemento deve corresponder exatamente ao nome de uma função em um arquivo JavaScript ou TypeScript. Se você alterá-lo no manifesto, altere-o no arquivo de código também.

Verifique se suas permissões de solicitações de suplemento do SSO

Se o suplemento usar o logon único da Microsoft com o fluxo em nome do (OBO), o suplemento terá um <elemento Scopes> que especifica o Microsoft Graph ou outras permissões de API que o suplemento precisa. Com o manifesto unificado, as permissões devem ser solicitadas em runtime no código. Atualize seu código conforme necessário para solicitar essas permissões. O código exato depende das bibliotecas de código de arquitetura e autorização que você está usando. Normalmente, o código solicita permissões em uma função que solicita um token de acesso.

Ferramentas e opções de conversão

Há várias maneiras de executar as tarefas restantes, dependendo do IDE e de outras ferramentas que você deseja usar para seu projeto e da ferramenta usada para criar o projeto.

Converter o projeto com o Teams Toolkit

A maneira mais fácil de converter é usar o Teams Toolkit.

Pré-requisitos

Importar o projeto de suplemento para o Teams Toolkit

  1. Abra Visual Studio Code e selecione o ícone Kit de Ferramentas do Teams na Barra de Atividades.

    Ícone kit de ferramentas do Teams.

  2. Selecione Create um novo aplicativo.

  3. Na lista suspensa Novo Projeto , selecione Suplemento do Outlook.

    As quatro opções em Novo Projeto são suspensas. A quarta opção é chamada de

  4. Na lista suspensa Recursos do aplicativo Usando um suplemento do Outlook , selecione Importar um suplemento do Outlook existente.

    As duas opções nos recursos de aplicativo usando uma lista suspensa do Suplemento do Outlook. A segunda opção é chamada

  5. Na pasta de projeto de suplemento existente suspensa, navegue até a pasta raiz do projeto de suplemento.

  6. Na lista suspensa Selecionar arquivo de manifesto de importação de projeto , navegue até o arquivo de manifesto XML.

  7. Na caixa de diálogo Pasta do Workspace , selecione a pasta em que você deseja colocar o projeto convertido.

  8. Na caixa de diálogo Nome do aplicativo , dê um nome ao projeto (sem espaços). O Teams Toolkit cria o projeto com seus arquivos de origem e scaffolding. Em seguida, ele abre o projeto em uma segunda janela Visual Studio Code. Feche a janela de Visual Studio Code original.

Carregar de lado o suplemento no Visual Studio Code

Você pode sideload do suplemento usando o Kit de Ferramentas do Teams ou em um prompt de comando, shell bash ou terminal.

Sideload com o Kit de Ferramentas do Teams
  1. Primeiro, verifique se a área de trabalho do Outlook está fechada.
  2. Em Visual Studio Code, abra o Kit de Ferramentas do Teams.
  3. Na seção ACCOUNTS , verifique se você está conectado ao Microsoft 365.
  4. Selecione Exibir | Executar em Visual Studio Code. No menu suspenso EXECUTAR E DEPURAR, selecione a opção Outlook Desktop (Edge Chromium)e pressione F5. O projeto cria e uma janela do servidor de desenvolvimento do Nó é aberta. Esse processo pode levar alguns minutos e, em seguida, a área de trabalho do Outlook é aberta.
  5. Agora você pode trabalhar com seu suplemento. Certifique-se de que você está trabalhando na caixa de entrada da sua identidade de conta do Microsoft 365.
Sideload com um prompt do sistema, shell bash ou terminal
  1. Primeiro, verifique se a área de trabalho do Outlook está fechada.
  2. Abra um prompt do sistema, o shell bash ou o TERMINAL Visual Studio Code e navegue até a raiz do projeto.
  3. Execute o comando npm run start:desktop. O projeto cria e uma janela do servidor de desenvolvimento do Nó é aberta. Esse processo pode levar alguns minutos e a área de trabalho do Outlook será aberta.
  4. Agora você pode trabalhar com seu suplemento.

Projetos criados com o Gerador do Office Yeoman (também conhecido como "Yo Office")

Se o projeto foi criado com o Gerador do Office Yeoman e você não quiser usar o Kit de Ferramentas do Teams, converta-o usando as etapas a seguir.

  1. Na raiz do projeto, abra um prompt de comando ou shell bash e execute o comando a seguir. Isso converte o manifesto e atualiza o package.json para especificar pacotes de ferramentas atuais. O novo manifesto unificado está na raiz do projeto e o manifesto XML antigo está em um arquivo backup.zip. Para obter detalhes sobre esse comando, consulte Office-Addin-Project.

    npx office-addin-project convert -m <relative-path-to-XML-manifest>

  2. Execute npm install.

  3. Para carregar o suplemento, execute npm run start:desktop. Esse comando coloca o manifesto unificado e os dois arquivos de imagem em um arquivo zip e o carrega de lado no aplicativo do Office. Ele também inicia o servidor em uma janela nodeJS separada para hospedar os arquivos de suplemento no localhost.

Projetos nodeJS e npm que não são criados com o Gerador yeoman

Se você não quiser usar o Teams Toolkit e seu projeto não tiver sido criado com o gerador do Office Yeoman, use a ferramenta office-addin-manifest-converter.

Na raiz do projeto, abra um prompt de comando ou shell bash e execute o comando a seguir. Esse comando coloca o manifesto unificado em uma subpasta com o mesmo nome que o caule de nome de arquivo do manifesto XML original. Por exemplo, se o manifesto for nomeado MyManifest.xml, o manifesto unificado será criado em .\MyManifest\MyManifest.json. Para obter mais detalhes sobre esse comando, consulte Office-Addin-Manifest-Converter.

npx office-addin-manifest-converter convert -m <relative-path-to-XML-manifest>

Depois que você tiver o manifesto unificado criado, há duas maneiras de criar o arquivo zip e recarregá-lo. Eles são descritos nas duas próximas subseções.

Sideload com a ferramenta Office-Addin-Debugging

  1. Para carregar o suplemento, execute o comando a seguir. Esse comando coloca o manifesto unificado e dois arquivos de imagem de ícone padrão em um arquivo zip e o carrega de lado no aplicativo do Office. Ele também inicia um servidor em uma janela nodeJS separada para hospedar os arquivos de suplemento em localhost. Observe que você passa o caminho para o manifesto unificado criado na etapa anterior. Para obter mais detalhes sobre esse comando, consulte Office-Addin-Debugging.

    npx office-addin-debugging start <relative-path-to-unified-manifest> desktop

  2. Quando você usa o office-addin-debugging para iniciar um suplemento, sempre interrompa a sessão com o comando a seguir. Fechar a janela do servidor não interrompe de forma confiável o servidor e fechar o aplicativo do Office não faz com que o Office desaquiva o suplemento de forma confiável.

    npx office-addin-debugging stop <relative-path-to-unified-manifest>

Sideload com a CLI do Teams Toolkit (interface de linha de comando)

  1. Crie manualmente o pacote zip usando as etapas a seguir.

    1. Abra o manifesto unificado e role até a propriedade "ícones". Observe o caminho relativo dos dois arquivos de imagem.
    2. Use qualquer utilitário zip para criar um arquivo zip que contenha o manifesto unificado e os dois arquivos de imagem. Os arquivos de imagem devem ter o mesmo caminho relativo no arquivo zip do que no projeto. Por exemplo, se o caminho relativo for "ativos/icon-64.png" e "ativos/icon-128.png", você deverá incluir a pasta "ativos" com os dois arquivos no pacote zip.
    3. Se a pasta contiver outros arquivos, como arquivos de imagem usados na faixa de opções do Office, remova-os do pacote zip. Ele deve ter apenas os dois arquivos de imagem especificados na propriedade "ícones" (além do manifesto na raiz do pacote zip).

  2. Na raiz do projeto, abra um prompt de comando ou shell bash e execute os comandos a seguir.

    npm install -g @microsoft/teamsfx-cli

teamsfx m365 sideloading --file-path <relative-path-to-zip-file>