Creación de un manifiesto de paquete

  • Artículo

Si quiere enviar un paquete de software al repositorio de la comunidad del Administrador de paquetes de Windows, cree un manifiesto de paquete para empezar. El manifiesto es un archivo YAML que describe la aplicación que se va a instalar.

Puede usar el creador de manifiestos del Administrador de paquetes de Windows, el script de PowerShell YAMLCreate o puede crear un manifiesto manualmente siguiendo las instrucciones siguientes.

Nota

Consulte las preguntas más frecuentes sobre el manifiesto a continuación para obtener información general de alto nivel que explica los manifiestos, los paquetes y las versiones.

Opciones para la creación de manifiestos

Uso de la utilidad WinGetCreate

Puede instalar la utilidad wingetcreate mediante el comando siguiente.

winget install wingetcreate

Después de la instalación, puede ejecutar wingetcreate new para crear un nuevo paquete y rellenar las solicitudes. La última opción que WinGetCreate ofrecerá es enviar el manifiesto al repositorio de paquetes. Si elige sí, enviará automáticamente la solicitud de extracción (pull request) (PR) al repositorio de la comunidad del Administrador de paquetes de Windows.

Uso de YAMLCreate.ps1

Para ayudar a crear archivos de manifiesto, hemos proporcionado el script YAMLCreate.ps1 de Powershell ubicado en la carpeta Herramientas del repositorio de la comunidad del Administrador de paquetes de Windows. Puede usar el script clonando el repositorio del equipo y ejecutándolo directamente desde la carpeta Herramientas. El script le pedirá la dirección URL al instalador y, a continuación, le pedirá que rellene los metadatos. De forma similar al uso de WinGetCreate, este script le ofrecerá la opción de enviar el manifiesto automáticamente.

Aspectos básicos de YAML

El formato YAML se eligió para los manifiestos de paquete debido a la facilidad de legibilidad humana y la coherencia con otras herramientas de desarrollo de Microsoft. Si no estás familiarizado con la sintaxis de YAML, puedes obtener información sobre los conceptos básicos en Learn YAML in Y Minutes.

Nota

Actualmente, los manifiestos para el Administrador de paquetes de Windows no admiten todas las características de YAML. Entre las características de YAML que no se admiten se incluyen delimitadores, claves complejas y conjuntos.

Convenciones

En este artículo se usan las convenciones siguientes:

  • A la izquierda de : hay una palabra clave literal que se usa en las definiciones del manifiesto.
  • A la derecha de : hay un tipo de datos. El tipo de datos puede ser de un tipo primitivo, como string, o una referencia a una estructura enriquecida definida en otra parte de este artículo.
  • La notación [ datatype ] indica una matriz del tipo de datos mencionado. Por ejemplo, [ string ] es una matriz de cadenas.
  • La notación { datatype : datatype } indica una asignación de un tipo de datos a otro. Por ejemplo, { string: string } es una asignación de cadenas a cadenas.

Contenido del manifiesto

Un manifiesto de paquete está compuesto de un conjunto de elementos obligatorios y opcionales que pueden ayudarle a mejorar la experiencia del cliente al instalar el software. En esta sección se proporciona un breve resumen del esquema de manifiesto obligatorio y los esquemas de manifiesto completos, así como ejemplos de cada uno.

Cada campo del archivo de manifiesto debe usar mayúsculas y minúsculas como en Pascal y no se puede duplicar.

Para ver una lista completa y descripciones de los elementos de un manifiesto, consulte la especificación del manifiesto en el repositorio de la comunidad del Administrador de paquetes de Windows.

Esquema obligatorio mínimo

Como se especifica en el esquema singleton de JSON, solo determinados campos son obligatorios. El archivo YAML mínimo admitido se parecería al ejemplo siguiente. El formato singleton solo es válido para los paquetes que contienen un solo instalador y una única configuración regional. Si se proporciona más de un instalador o configuración regional, se deben usar los varios formatos y esquemas de archivo YAML.

El esquema de creación de particiones se agregó para ayudar con la experiencia de usuario de GitHub. Las carpetas con miles de elementos secundarios no se representan bien en el explorador.

PackageIdentifier:  # Publisher.package format.
PackageVersion:     # Version numbering format.
PackageLocale:      # BCP 47 format (e.g. en-US)
Publisher:          # The name of the publisher.
PackageName:        # The name of the application.
License:            # The license of the application.
ShortDescription:   # The description of the application.
Installers: 
 - Architecture:    # Enumeration of supported architectures.
   InstallerType:   # Enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx).
   InstallerUrl:    # Path to download installation file.
   InstallerSha256: # SHA256 calculated from installer.
ManifestType:       # The manifest file type
ManifestVersion: 1.6.0

Varios archivos de manifiesto

Para proporcionar la mejor experiencia de usuario, los manifiestos deben contener tantos metadatos como sea posible. Para separar los problemas de validación de instaladores y proporcionar metadatos localizados, los manifiestos deben dividirse en varios archivos. El número mínimo de archivos YAML para este tipo de manifiesto es de tres. También se deben proporcionar configuraciones regionales adicionales.

En el ejemplo siguiente se muestran muchos campos de metadatos opcionales y varias configuraciones regionales. Tenga en cuenta que la configuración regional predeterminada tiene más requisitos que las configuraciones regionales adicionales. En el comando show, los campos obligatorios que no se proporcionan para configuraciones regionales adicionales mostrarán campos de la configuración regional predeterminada.

Ruta de acceso: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.yaml

PackageIdentifier: "Microsoft.WindowsTerminal"
PackageVersion: "1.6.10571.0"
DefaultLocale: "en-US"
ManifestType: "version"
ManifestVersion: "1.6.0"

Nota

Si el instalador es un archivo .exe y se compiló con Nullsoft o Inno, puede especificar esos valores en su lugar. Cuando se especifique Nullsoft o Inno, el cliente establecerá automáticamente los comportamientos de instalación silenciosa y silenciosa con progreso para el instalador.

Cambios del instalador

A menudo, puede averiguar qué elementos Switches silenciosos están disponibles para un instalador al pasar -? al instalador desde la línea de comandos. Estos son algunos de los elementos Switches silenciosos habituales que se pueden usar para distintos tipos de instalador.

Instalador Comando Documentación
MSI /q Opciones de la línea de comandos MSI
InstallShield /s Parámetros de la línea de comandos InstallShield
Inno Setup /SILENT or /VERYSILENT Documentación de Inno Setup
Nullsoft /S Instaladores/desinstaladores silenciosos de Nullsoft

Sugerencias y procedimientos recomendados

  • El identificador del paquete debe ser único. No puedes hacer varios envíos con el mismo identificador de paquete. Solo se permite una solicitud de incorporación de cambios por versión de paquete.
  • Evite crear varias carpetas de editor. Por ejemplo, no cree "Contoso Ltd" si ya existe una carpeta "Contoso".
  • Todas las herramientas deben admitir una instalación silenciosa. Si tiene un archivo ejecutable que no admite una instalación silenciosa, no podemos proporcionar una herramienta tal en este momento.
  • Proporcione tantos campos como sea posible. Entre más metadatos proporcione, mejor será la experiencia del usuario. En algunos casos, es posible que el cliente del Administrador de paquetes de Windows (winget.exe) no admita los campos. Por ejemplo, el campo AppMoniker es opcional. Sin embargo, si incluyes este campo, los clientes verán los resultados asociados con el valor de la Moniker al ejecutar el comando search (por ejemplo, vscode para Visual Studio Code). Si solo hay una aplicación con el valor Moniker especificado, los clientes podrán instalar la aplicación si escriben el moniker en lugar del identificador completo del paquete.
  • La longitud de las cadenas de esta especificación debe limitarse a 100 caracteres antes de un salto de línea.
  • PackageName debe coincidir con la entrada realizada en Agregar o quitar programas para ayudar a la correlación con manifiestos para admitir export y upgrade.
  • Publisher debe coincidir con la entrada realizada en Agregar o quitar programas para ayudar a la correlación con manifiestos para admitir export y upgrade.
  • Los instaladores de paquetes en formato MSI usan códigos de producto para identificar aplicaciones de forma única. El código de producto de una versión determinada de un paquete debe incluirse en el manifiesto para ayudar a garantizar la mejor experiencia de upgrade.
  • Cuando exista más de un tipo de instalador para la versión especificada del paquete, se puede colocar una instancia de InstallerType en cada una de las instancias de Installers.

Preguntas más frecuentes sobre manifiestos

¿Qué es un manifiesto?

Los manifiestos son archivos YAML que contienen metadatos que usa el Administrador de paquetes de Windows para instalar y actualizar software en el sistema operativo Windows. Hay miles de estos archivos particionados en el directorio de manifiestos del repositorio winget-pkgs en GitHub. La estructura de directorios del Administrador de paquetes de Windows tiene que particionarse para que no tenga que desplazarse tanto a lo largo del sitio al buscar un manifiesto.

¿Qué es un paquete?

Piense en un paquete como una aplicación o un programa de software. El Administrador de paquetes de Windows usa un elemento "PackageIdentifier" para representar un paquete único. Por lo general, se trata de Publisher.Package. A veces, es posible que vea valores adicionales separados por un segundo período.

¿Qué es una versión?

Las versiones del paquete están asociadas a una versión específica. En algunos casos, verá números de versión semántica perfectamente formados y, en otros casos, puede ver algo diferente. Estos elementos se pueden controlar con fechas o pueden tener otros caracteres con algún significado específico del paquete. La clave YAML de una versión del paquete es "PackageVersion".

Para obtener más información sobre cómo comprender la estructura de directorios y crear el primer manifiesto, consulte Creación de manifiestos en el repositorio winget-pkgs en GitHub.