Compartilhar via

Converter um suplemento para utilizar o manifesto unificado do Microsoft 365

  • Artigo

Para adicionar funcionalidades do Teams a um suplemento que utiliza o manifesto apenas de suplemento ou apenas para comprovativo futuro do suplemento, tem de convertê-lo para utilizar o manifesto unificado para o Microsoft 365.

Existem três tarefas básicas para converter um projeto de suplemento do manifesto apenas do suplemento para o manifesto unificado.

  • Certifique-se de que o suplemento está pronto para ser convertido.
  • Converta o próprio manifesto do suplemento formatado em XML para o formato JSON do manifesto unificado.
  • Empacote o novo manifesto e os dois ficheiros de imagem de ícone num ficheiro zip para sideloading ou implementação.

Observação

Os Suplementos do Office que utilizam o manifesto unificado do Microsoft 365 são diretamente suportados no Office na Web, no novo Outlook no Windows e no Office no Windows ligado a uma subscrição do Microsoft 365, Versão 2304 (Compilação 16320.00000) ou posterior.

Quando o pacote de aplicação que contém o manifesto unificado é implementado no AppSource ou no Centro de Administração Microsoft 365, é gerado um manifesto apenas de suplemento a partir do manifesto unificado e armazenado. Este manifesto apenas de suplemento permite que o suplemento seja instalado em plataformas que não suportam diretamente o manifesto unificado, incluindo o Office no Mac, o Office em dispositivos móveis, versões de subscrição do Office no Windows anteriores à 2304 (Compilação 16320.00000) e versões perpétuas do Office no Windows.

Observação

  • Os suplementos que utilizam o manifesto unificado só podem ser sideloaded na Versão 2304 do Office (Compilação 16320.20000) ou posterior.
  • De momento, os projetos criados no Visual Studio, distintos dos Visual Studio Code, não podem ser convertidos.
  • Se tiver criado o projeto com o Teams Toolkit ou com a opção "manifesto unificado" no Gerador Yeoman do Office, este já utiliza o manifesto unificado.

Certifique-se de que o suplemento está pronto para ser convertido

As secções seguintes descrevem as condições que têm de ser cumpridas antes de converter o manifesto.

Certifique-se de que tem os dois ficheiros de imagem

Quando tiver adicionado os ficheiros ao projeto, adicione <IconUrl> e <HighResolutionIconUrl> (por essa ordem) ao manifesto de suplemento apenas abaixo do <elemento Descrição> . 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 -->

Certifique-se de que os nomes dos comandos da função são suficientemente curtos

Se o seu manifesto tiver elementos <FunctionName> , certifique-se de que os respetivos valores têm menos de 65 carateres. O valor deste elemento tem de corresponder exatamente ao nome de uma função num ficheiro JavaScript ou TypeScript. Se o alterar no manifesto, certifique-se de que também o altera no ficheiro de código.

Certifique-se de que o suplemento SSO pede permissões

Se o suplemento utilizar o início de sessão único da Microsoft com o fluxo em nome de (OBO), o suplemento tem um <elemento Âmbitos> que especifica o Microsoft Graph ou outras permissões de API de que o suplemento precisa. Com o manifesto unificado, as permissões têm de ser pedidas no runtime no código. Atualize o código conforme necessário para pedir estas permissões. O código exato depende da arquitetura e das bibliotecas de código de autorização que está a utilizar. Normalmente, o código pede permissões numa função que pede um token de acesso.

Ferramentas e opções de conversão

Existem várias formas de realizar as tarefas restantes, consoante o IDE e outras ferramentas que pretende utilizar para o seu projeto e na ferramenta que utilizou para criar o projeto.

Converter o projeto com o Teams Toolkit

A forma mais fácil de converter é utilizar o Teams Toolkit.

Pré-requisitos

Importar o projeto de suplemento para o Teams Toolkit

  1. Abra Visual Studio Code e selecione o ícone do Toolkit do Teams na Barra de Atividade.

    Ícone do Toolkit do Teams.

  2. Selecione Criar uma nova aplicação.

  3. No menu pendente Novo Projeto , selecione Suplemento do Outlook.

    As quatro opções no menu pendente Novo Projeto. A quarta opção chama-se

  4. No menu pendente Funcionalidades da Aplicação Utilizar um Suplemento do Outlook , selecione Importar um Suplemento existente do Outlook.

    As duas opções no menu pendente Funcionalidades da Aplicação Utilizar um Suplemento do Outlook. A segunda opção chama-se

  5. No menu pendente Pasta do projeto de suplemento existente , navegue para a pasta raiz do projeto de suplemento.

  6. No menu pendente Selecionar ficheiro de manifesto importar projeto , navegue para o ficheiro de manifesto apenas do suplemento, normalmente denominado manifest.xml.

  7. Na caixa de diálogo pasta Área de Trabalho , selecione a pasta onde pretende colocar o projeto convertido.

  8. Na caixa de diálogo Nome da aplicação, atribua um nome ao projeto (sem espaços). O Teams Toolkit cria o projeto com os seus ficheiros de origem e estrutura. Em seguida, abre o projeto numa segunda janela Visual Studio Code. Feche a janela de Visual Studio Code original.

Sideload the add-in in Visual Studio Code

Pode fazer sideload do suplemento com o Toolkit do Teams ou numa linha de comandos, shell de bash ou terminal.

Sideload com o Teams Toolkit
  1. Primeiro, certifique-se de que o Outlook para ambiente de trabalho está fechado.
  2. No Visual Studio Code, abra o Toolkit do Teams.
  3. Na secção CONTAS , verifique se tem sessão iniciada no Microsoft 365.
  4. Selecione Ver | Executar no Visual Studio Code. No menu pendente EXECUTAR E DEPURAR, selecione a opção Ambiente de Trabalho do Outlook (Edge Chromium) e, em seguida, prima F5. O projeto é compilação e é aberta uma janela Dev-Server do Nó. Este processo pode demorar alguns minutos e, em seguida, o Outlook para ambiente de trabalho é aberto.
  5. Agora pode trabalhar com o seu suplemento. Certifique-se de que está a trabalhar na Caixa de Entrada da sua identidade de conta do Microsoft 365.
Sideload com uma linha de comandos do sistema, shell bash ou terminal
  1. Primeiro, certifique-se de que o Outlook para ambiente de trabalho está fechado.
  2. Abra uma linha de comandos do sistema, a shell do bash ou a Visual Studio Code TERMINAL e navegue para a raiz do projeto.
  3. Se a secção "scripts" do ficheiro de package.json do projeto tiver um script "start:desktop", execute npm run start:desktop; caso contrário, execute npm run start. O projeto é compilação e é aberta uma janela Dev-Server do Nó. Este processo pode demorar alguns minutos e, em seguida, o Outlook para ambiente de trabalho é aberto.
  4. Agora pode trabalhar com o seu suplemento.
  5. Quando terminar de trabalhar com o suplemento, certifique-se de que executa o comando npm run stop.

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

Se o projeto tiver sido criado com o Gerador Yeoman do Office e não quiser utilizar o Toolkit do Teams, converta-o com os seguintes passos.

  1. Na raiz do projeto, abra uma linha de comandos ou shell de bash e execute o seguinte comando. Isto converte o manifesto e atualiza o package.json para especificar os pacotes de ferramentas atuais. O novo manifesto unificado está na raiz do projeto e o manifesto do suplemento antigo está num ficheiro backup.zip. Para obter detalhes sobre este comando, consulte Office-Addin-Project.

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

  2. Execute npm install.

  3. O comando para fazer sideload do suplemento depende de quando o projeto foi criado. Se a secção "scripts" do ficheiro de package.json do projeto tiver um script "start:desktop", execute npm run start:desktop; caso contrário, execute npm run start. Este comando coloca o manifesto unificado e os dois ficheiros de imagem num ficheiro zip e faz o sideload para a aplicação do Office. Também inicia o servidor numa janela do NodeJS separada para alojar os ficheiros de suplemento no localhost.

Quando estiver pronto para parar o servidor dev e desinstalar o suplemento, execute o comando npm run stop.

Projetos NodeJS e npm que não são criados com o Yeoman Generator

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

Na raiz do projeto, abra uma linha de comandos ou shell de bash e execute o seguinte comando. Este comando coloca o manifesto unificado numa subpasta com o mesmo nome que o caule de nome de ficheiro do manifesto apenas do suplemento original. Por exemplo, se o manifesto tiver o nome MyManifest.xml, o manifesto unificado é criado em .\MyManifest\MyManifest.json. Para obter mais detalhes sobre este comando, consulte Office-Addin-Manifest-Converter.

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

Depois de criar o manifesto unificado, existem duas formas de criar o ficheiro zip e de o fazer sideload. São descritas nas duas subsecções seguintes.

Sideload com a ferramenta Office-Addin-Debugging

  1. Para colocar o suplemento em sideload, execute o seguinte comando. Este comando coloca o manifesto unificado e dois ficheiros de imagem de ícone predefinidos num ficheiro zip e faz o sideload para a aplicação do Office. Também inicia um servidor numa janela do NodeJS separada para alojar os ficheiros de suplemento no localhost. Tenha em atenção que transmite o caminho para o manifesto unificado que criou no passo anterior. Para obter mais detalhes sobre este comando, consulte Office-Addin-Debugging.

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

  2. Quando utiliza office-addin-debugging para iniciar um suplemento, pare sempre a sessão com o seguinte comando. Fechar a janela do servidor não para de forma fiável o servidor e fechar a aplicação do Office não faz com que o Office não se preocupe com o suplemento.

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

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

  1. Crie manualmente o pacote zip com os seguintes passos.

    1. Abra o manifesto unificado e desloque-se para a propriedade "ícones". Tenha em atenção o caminho relativo dos dois ficheiros de imagem.
    2. Utilize qualquer utilitário zip para criar um ficheiro zip que contenha o manifesto unificado e os dois ficheiros de imagem. Os ficheiros de imagem têm de ter o mesmo caminho relativo no ficheiro zip que têm no projeto. Por exemplo, se o caminho relativo for "assets/icon-64.png" e "assets/icon-128.png", tem de incluir a pasta "assets" com os dois ficheiros no pacote zip.
    3. Se a pasta contiver outros ficheiros, como ficheiros de imagem utilizados no friso do Office, remova-os do pacote zip. Deve ter apenas os dois ficheiros de imagem especificados na propriedade "ícones" (para além do manifesto na raiz do pacote zip).

  2. Na raiz do projeto, abra uma linha de comandos ou shell de bash e execute os seguintes comandos.

    npm install -g @microsoft/teamsapp-cli

teamsapp install --file-path <relative-path-to-zip-file>

  3. Quando utiliza a CLI do Teams Toolkit para iniciar um suplemento, pare sempre a sessão com o seguinte comando. Fechar a janela do servidor não para de forma fiável o servidor e fechar a aplicação do Office não faz com que o Office não se preocupe com o suplemento. Substitua o "{GUID do suplemento}" pelo GUID na propriedade "id" do manifesto unificado.

    teamsapp uninstall -manifest-id {GUID of the add-in}