Converter um suplemento para usar o manifesto unificado do Microsoft 365 (versão prévia)

  • 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 você tem arquivos de imagens de 64x64 pixels e 128x128 pixels para servir como ícones para o suplemento.
  • Converta o manifesto XML em si no formato JSON do manifesto unificado.
  • Empacotar o novo manifesto e main ícone e arquivos de imagem de ícone de alta resolução em um arquivo zip para sideload ou implantação.

Observação

  • O manifesto unificado é um recurso de visualização para suplementos do Office e atualmente tem suporte apenas para o Outlook no Windows.
  • Os suplementos que usam o manifesto unificado só podem ser carregados de lado no Office Build 16.0.16501.10000 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 você tem os dois arquivos de imagem

É altamente provável que você tenha os dois arquivos de imagem já em seu suplemento. Eles são especificados nos elementos IconUrl e HighResolutionIconUrl no manifesto XML. Como ambos são elementos opcionais, o mignt do projeto de suplemento não tem um ou ambos. Eles são necessários para um suplemento que usa o manifesto unificado, portanto, você precisa criá-los se o projeto ainda não os tiver. Para obter diretrizes, consulte Create um ícone para seu suplemento.

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 -->

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 (usando qualquer opção, exceto a opção "manifesto unificado") 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>