Especificar requisitos de suplemento do Office no manifesto unificado do Microsoft 365

Há várias propriedades de "requisitos" no manifesto unificado do Microsoft 365. A propriedade extensions.requirements controla os aplicativos do Office e versões nas quais o suplemento pode ser instalado. Outras propriedades "requisitos" são usadas para suprimir seletivamente alguns recursos de um suplemento em aplicativos ou versões específicas do Office em que esses recursos seriam desnecessários ou sem suporte. Para obter mais informações, consulte Filtrar recursos.

extensions.requirements

A propriedade "extensions.requirements" especifica os escopos, os fatores de formulário e os conjuntos de requisitos para suplementos do Microsoft 365. Se a versão do Microsoft 365 não der suporte aos requisitos especificados, a extensão não estará disponível para instalação. Os usuários não o verão na interface do usuário do Office para pesquisar e instalar suplementos. Alguns exemplos:

• Se a propriedade "requirements.capabilities.name" estiver definida como "Caixa de Correio" e "requirements.capabilities.minVersion" como "1.10", o suplemento não poderá ser instalado em versões mais antigas do Office que não dão suporte a conjuntos de requisitos da caixa de correio maiores que a versão 1.9.
• Se os "requirements.scopes" forem definidos como "email", o suplemento só poderá ser instalado no Outlook.
• Se o "requirements.formFactors" for definido apenas como "desktop", o suplemento não poderá ser instalado no Office em execução em um dispositivo móvel.

Você pode ter mais de um objeto de funcionalidade. O exemplo a seguir mostra como garantir que um suplemento seja instalado apenas em versões do Office que dão suporte a dois conjuntos de requisitos diferentes e não em dispositivos móveis.

"extensions": [
    ...
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.10"
            },
            {
                "name": "DialogAPI",
                "minVersion": "1.2"
            }
        ],
        "formFactors": [
            "desktop"
        ]
    }
]

Filtrar recursos

As propriedades "requisitos" em objetos descendentes de "extensões" são usadas para bloquear alguns recursos de um suplemento enquanto ainda permitem que o suplemento seja instalado. A implementação dessa filtragem é feita na origem da instalação, como AppSource ou Administração Microsoft 365 Center. Se a versão do Office não dá suporte aos requisitos especificados para o recurso, o nó JSON do recurso será removido do manifesto antes de ser instalado no aplicativo do Office.

extensions.alternates.requirements

A propriedade "extensions.alternates" permite que os desenvolvedores de suplementos façam o seguinte:

• Mantenha uma versão de um suplemento que foi criado em uma plataforma de extensibilidade mais antiga (como suplementos COM ou VSTO) ou usando o manifesto XML, além da versão que usa o manifesto unificado.
• Ocultar ou dar preferência à versão que usa a tecnologia mais antiga.
• Especifique ícones necessários para tornar a versão de manifesto unificada do suplemento instalável em versões do Office que não dão suporte direto ao manifesto unificado.

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.

Para obter mais informações, consulte Gerenciar um manifesto unificado e uma versão de manifesto XML do suplemento do Office.

A subpropertia "requisitos" de "extensions.alternates" para aplicar seletivamente as subpropertidades "ocultar" ou "preferir" somente quando determinados requisitos forem atendidos.

Por exemplo, suponha que você queira ocultar (da interface do usuário do Office para instalar suplementos) uma versão mais antiga do suplemento, mas apenas em versões do Office que dão suporte ao conjunto de requisitos da Caixa de Correio 1.10 . Você pode fazer isso com marcação semelhante à seguinte:

"extensions": [
    ...
    {
        ...
        "alternates": [
            ...
            {
                ...
                "hide": {
                    "storeOfficeAddin": {
                        "officeAddinId": "b5a2794d-4aa5-4023-a84b-c60a3cbd33d4",
                        "assetId": "WA999999999"
                    }
                },
                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.10"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.autoRunEvents.requirements

A propriedade "extensions.autoRunEvents" configura um suplemento para executar o código especificado automaticamente em resposta a eventos especificados. A subpropertia "requisitos" pode ser usada para bloquear esse comportamento em algumas versões do Office.

Por exemplo, suponha que um suplemento do Outlook esteja configurado para iniciar automaticamente em resposta ao evento OnMailSend e suponha que o código na função executada requer o conjunto de requisitos mailbox 1.13 . Mas o suplemento tem outros recursos que seriam úteis nas versões do Office que só dão suporte à versão 1.12. Para garantir que o suplemento seja instalável em versões que dão suporte a 1.12, um desenvolvedor pode definir a propriedade "extensions.requirements.capabilities" para o conjunto de requisitos Mailbox 1.12 em vez de 1.13. Mas para bloquear o recurso de lançamento automático em versões que não dão suporte ao 1.13, o desenvolvedor pode adicionar uma propriedade "extensions.autoRunEvents.requirements.capabilities" que especifica a Caixa de Correio 1.13. Apresentamos um exemplo a seguir.

"extensions": [
    ...
    {
        ...
        "autoRunEvents": [
            ...
            {
                ...
                "events": {
                    "type": "OnMailSend",
                    "actionId": "logOutgoingEmail",
                    "options": {
                        "sendMode": "promptUser"
                    }
                },
                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.13"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.ribbons.requirements

A propriedade "extensions.ribbons" é usada para personalizar a faixa de opções do aplicativo do Office quando o suplemento é instalado. A subpropertia "requisitos" pode ser usada para impedir as personalizações em algumas versões do Office.

Por exemplo, suponha que um suplemento do Outlook esteja configurado para adicionar um botão personalizado à faixa de opções e o botão execute uma função que usa o código introduzido no conjunto de requisitos da Caixa de Correio 1.9 . Mas o suplemento tem outros recursos que seriam úteis em versões do Office que só dão suporte à versão 1.8. Para garantir que o suplemento seja instalável em versões que dão suporte a 1.8, um desenvolvedor pode definir a propriedade "extensions.requirements.capabilities" para o conjunto de requisitos Mailbox 1.8 em vez de 1.9. Mas para impedir que o botão personalizado apareça na faixa de opções em versões que não dão suporte ao 1.9, o desenvolvedor pode adicionar uma propriedade "extensions.ribbons.requirements.capabilities" que especifica a Caixa de Correio 1.9. Apresentamos um exemplo a seguir. Para obter detalhes da configuração de faixa de opções personalizada, consulte Criar comandos de suplemento com o manifesto unificado do Microsoft 365.

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                // Insert details of the ribbon configuration here.

                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.9"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.runtimes.requirements

A propriedade "extensions.runtimes" configura os conjuntos de runtimes e ações que cada ponto de extensão pode usar. Para obter mais informações sobre seu uso, consulte Criar comandos de suplemento, Configure o runtime para um painel de tarefas e Configure o runtime para o comando de função. Para obter mais informações sobre runtimes em suplementos do Office, consulte Runtimes em Suplementos do Office.

A subpropertia "requisitos" pode ser usada para impedir que o runtime seja incluído em versões do Office ou em aplicativos do Office em que ele não seria usado.

O exemplo anterior mostrado em extensions.autoRunEvents.requirements mostra como bloquear o recurso de lançamento automático em versões que não dão suporte a todo o código na função, que inclui código logOutgoingEmail que requer a caixa de correio 1.13. Suponha que, nesse mesmo cenário, o objeto "runtime" configurado para dar suporte à ação "logOutgoingEmail" não esteja configurado para dar suporte a nenhuma outra ação. Nesse caso, o desenvolvedor deve bloquear o objeto runtime em versões que não dão suporte ao Mailbox 1.13 , pois ele nunca seria usado. Apresentamos um exemplo a seguir. Para obter detalhes da configuração de runtime, consulte Criar comandos de suplemento com o manifesto unificado do Microsoft 365.

"extensions": [
    ...
    {
        ...
        "runtimes": [
            ...
            {
                // Insert details of the runtime configuration here.

                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.13"
                        }
                    ]
                }
            }
        ]
    }
]

Da mesma forma, para o exemplo em extensions.ribbons.requirements, se a ação vinculada ao botão personalizado for a única ação configurada em um objeto runtime, esse objeto runtime deverá ser bloqueado nas mesmas circunstâncias em que o objeto de faixa de opções é bloqueado.