Especificar los requisitos de complementos de Office en el manifiesto unificado para Microsoft 365

Artículo
04/12/2024

Hay varias propiedades de "requisitos" en el manifiesto unificado para Microsoft 365. La propiedad extensions.requirements controla las aplicaciones y versiones de Office en las que se puede instalar el complemento. Otras propiedades de "requisitos" se usan para suprimir selectivamente algunas características de un complemento en aplicaciones o versiones específicas de Office en las que esas características serían innecesarias o no admitidas. Para obtener más información, consulte Características de filtro.

extensions.requirements

La propiedad "extensions.requirements" especifica los ámbitos, los factores de forma y los conjuntos de requisitos de los complementos de Microsoft 365. Si la versión de Microsoft 365 no admite los requisitos especificados, la extensión no estará disponible para la instalación. Los usuarios no lo verán en la interfaz de usuario de Office para buscar e instalar complementos. Algunos ejemplos:

Si la propiedad "requirements.capabilities.name" se establece en "Mailbox" y "requirements.capabilities.minVersion" en "1.10", el complemento no se puede instalar en versiones anteriores de Office que no admiten conjuntos de requisitos de buzón mayores que la versión 1.9.
Si "requirements.scopes" está establecido en "mail", el complemento solo se puede instalar en Outlook.
Si "requirements.formFactors" se establece en solo "escritorio", el complemento no se puede instalar en Office que se ejecuta en un dispositivo móvil.

Puede tener más de un objeto de funcionalidad. En el ejemplo siguiente se muestra cómo asegurarse de que un complemento solo se puede instalar en versiones de Office que admiten dos conjuntos de requisitos diferentes y no en dispositivos móviles.

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

Características de filtro

Las propiedades "requirements" de los objetos descendientes de "extensiones" se usan para bloquear algunas características de un complemento, a la vez que permiten instalar el complemento. La implementación de este filtrado se realiza en el origen de la instalación, como AppSource o Administración de Microsoft 365 Center. Si la versión de Office no admite los requisitos especificados para la característica, el nodo JSON de la característica se quita del manifiesto antes de que se instale en la aplicación de Office.

extensions.alternates.requirements

La propiedad "extensions.alternates" permite a los desarrolladores de complementos hacer lo siguiente:

Mantenga una versión de un complemento que se basa en una plataforma de extensibilidad anterior (como complementos COM o VSTO) o mediante el manifiesto XML, además de la versión que usa el manifiesto unificado.
Oculte o dé preferencia a la versión que usa la tecnología anterior.
Especifique los iconos necesarios para que la versión de manifiesto unificado del complemento se pueda instalar en versiones de Office que no admitan directamente el manifiesto unificado.

Nota:

Los complementos de Office que usan el manifiesto unificado para Microsoft 365 se admiten directamente en Office en la Web, en el nuevo Outlook en Windows (versión preliminar) y en Office en Windows conectado a una suscripción de Microsoft 365, versión 2304 (compilación 16320.00000) o posterior.

Cuando el paquete de aplicación que contiene el manifiesto unificado se implementa en AppSource o en el Centro de Administración de Microsoft 365, si el manifiesto tiene una propiedad "alternateIcons" válida, se genera un manifiesto XML a partir del manifiesto unificado y se almacena. Este manifiesto XML permite instalar el complemento en plataformas que no admiten directamente el manifiesto unificado, incluido Office en Mac, Office en dispositivos móviles, versiones de suscripción de Office en Windows anteriores a 2304 (compilación 16320.00000) y versiones perpetuas de Office en Windows.

Para obtener más información, vea Administrar un manifiesto unificado y una versión de manifiesto XML del complemento de Office.

La subpropiedad "requirements" de "extensions.alternates" para aplicar selectivamente las subpropiedades "hide" o "prefer" solo cuando se cumplen determinados requisitos.

Por ejemplo, supongamos que desea ocultar (desde la interfaz de usuario de Office para instalar complementos) una versión anterior del complemento, pero solo en las versiones de Office que admiten el conjunto de requisitos buzón 1.10 . Puede hacerlo con un marcado similar al siguiente:

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

extensions.autoRunEvents.requirements

La propiedad "extensions.autoRunEvents" configura un complemento para ejecutar automáticamente el código especificado en respuesta a los eventos especificados. La subpropiedad "requirements" se puede usar para bloquear este comportamiento en algunas versiones de Office.

Por ejemplo, supongamos que un complemento de Outlook está configurado para iniciarse automáticamente en respuesta al evento OnMailSend y suponga que el código de la función que se ejecuta requiere el conjunto de requisitos buzón 1.13 . Pero el complemento tiene otras características que serían útiles en las versiones de Office que solo admiten la versión 1.12. Para asegurarse de que el complemento se puede instalar en versiones que admiten la versión 1.12, un desarrollador puede establecer la propiedad "extensions.requirements.capabilities" en el conjunto de requisitos Mailbox 1.12 en lugar de 1.13. Pero para bloquear la característica de inicio automático en versiones que no admiten la versión 1.13, el desarrollador puede agregar una propiedad "extensions.autoRunEvents.requirements.capabilities" que especifique mailbox 1.13. A continuación se muestra un ejemplo.

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

extensions.ribbons.requirements

La propiedad "extensions.ribbons" se usa para personalizar la cinta de opciones de la aplicación de Office cuando se instala el complemento. La subpropiedad "requirements" se puede usar para evitar las personalizaciones en algunas versiones de Office.

Por ejemplo, supongamos que un complemento de Outlook está configurado para agregar un botón personalizado a la cinta de opciones y el botón ejecuta una función que usa código introducido en el conjunto de requisitos buzón 1.9 . Pero el complemento tiene otras características que serían útiles en las versiones de Office que solo admiten la versión 1.8. Para asegurarse de que el complemento se puede instalar en versiones que admiten la versión 1.8, un desarrollador puede establecer la propiedad "extensions.requirements.capabilities" en el conjunto de requisitos Mailbox 1.8 en lugar de 1.9. Pero para impedir que el botón personalizado aparezca en la cinta de opciones en versiones que no admiten la versión 1.9, el desarrollador puede agregar una propiedad "extensions.ribbons.requirements.capabilities" que especifique Mailbox 1.9. A continuación se muestra un ejemplo. Para obtener más información sobre la configuración de la cinta de opciones personalizada, consulte Creación de comandos de complemento con el manifiesto unificado para Microsoft 365.

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

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

extensions.runtimes.requirements

La propiedad "extensions.runtimes" configura los conjuntos de tiempos de ejecución y las acciones que puede usar cada punto de extensión. Para obtener más información sobre su uso, vea Crear comandos de complemento, Configurar el tiempo de ejecución para un panel de tareas y Configurar el tiempo de ejecución para el comando de función. Para obtener más información sobre los tiempos de ejecución en complementos de Office, vea Runtimes in Office Add-ins.

La subpropiedad "requirements" se puede usar para evitar que el tiempo de ejecución se incluya en versiones de Office o en aplicaciones de Office en las que no se usaría.

En el ejemplo anterior que se muestra en extensions.autoRunEvents.requirements se muestra cómo bloquear la característica de inicio automático en versiones que no admiten todo el código de la logOutgoingEmail función, que incluye código que requiere mailbox 1.13. Supongamos que, en ese mismo escenario, el objeto "runtime" configurado para admitir la acción "logOutgoingEmail" no está configurado para admitir ninguna otra acción. En ese caso, el desarrollador debe bloquear el objeto en tiempo de ejecución en versiones que no admitan mailbox 1.13 , ya que nunca se usaría. A continuación se muestra un ejemplo. Para obtener más información sobre la configuración del entorno de ejecución, consulte Creación de comandos de complemento con el manifiesto unificado para Microsoft 365.

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

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

De forma similar, en el ejemplo de extensions.ribbons.requirements, si la acción vinculada al botón personalizado es la única acción configurada en un objeto en tiempo de ejecución, ese objeto en tiempo de ejecución debe bloquearse en las mismas circunstancias en las que se bloquea el objeto de cinta de opciones.