Procedimiento para crear un archivo de configuración de WinGet

Artículo
09/28/2023

Para crear un archivo de configuración de WinGet:

Para crear un archivo YAML, siga la convención de nomenclatura de archivos de configuración de WinGet.
Familiarícese con el formato de un archivo de configuración de WinGet y vincule el esquema de archivo actual.
Determine la lista de Aserciones (condiciones previas necesarias) y Recursos (la lista de instalaciones necesarias y las configuraciones para lograr el estado deseado en el entorno de desarrollo del equipo) que se incluirá en el archivo.
Identifique los módulos de PowerShell y los recursos de Desired State Configuration (DSC) necesarios para realizar las tareas de configuración deseadas.
Determine las directivas y los valores necesarios para cada recurso de configuración.
Determine las dependencias de cada recurso.

Obtenga más información sobre el uso del comando WinGet configure.

Formato de archivo

Administrador de paquetes de Windows usa manifiestos (archivos YAML) a fin de buscar e instalar paquetes para usuarios de Windows. Los archivos de configuración de WinGet usan el mismo formato de estilo YAML, y agregan una especificación de esquema JSON para ayudar a definir la estructura y la validación del archivo. Para ayudar aún más a detectar si el formato del archivo de configuración de WinGet es válido, se recomienda usar Visual Studio Code con la extensión YAML de RedHat para admitir la sintaxis adecuada, ayudar a detectar errores de formato, proporcionar compatibilidad con el mantenimiento del puntero y finalización automática (cuando se vincula al archivo de esquema JSON) y garantizar el formato válido.

Convención de nomenclatura de archivos

La convención de nomenclatura de un archivo de configuración de WinGet es configuration.dsc.yaml. En el caso de los proyectos basados en Git, la configuración predeterminada se debe almacenar en un directorio "configurations" en: ./configurations/configuration.dsc.yaml.

Secciones de un archivo de configuración de WinGet

Un archivo de configuración de WinGet se divide en dos secciones principales:

Aserciones: condiciones previas necesarias para ejecutar la configuración.
Recursos: la lista de software y herramientas que se van a instalar, las opciones de configuración de esas instalaciones y las del sistema operativo Windows.

Sección Aserciones

La lista de aserciones abarca las condiciones previas (o requisitos previos) necesarias para que los recursos enumerados en este archivo de configuración de WinGet sean correctos en la máquina que ejecuta el archivo. Las aserciones se pueden completar en paralelo y no necesitan ningún orden secuencial.

Una aserción de ejemplo:

Versión del sistema operativo: versión mínima del sistema operativo* instalada en la máquina. A medida que se agregan características al sistema operativo, de algunas se realiza la portabilidad para admitir versiones anteriores y de otras no. Siempre resulta útil comprobar si hay una versión mínima del sistema operativo para determinar si se puede admitir una herramienta o característica específica necesaria para la configuración. Por ejemplo, WinGet (Administrador de paquetes de Windows) necesita, como mínimo, Windows 10, versión 1809 o posterior. Las versiones anteriores de Windows no admiten WinGet. *Es posible que los recursos de DSC de PowerShell cambien el estado del sistema, pero no sería adecuado llamar a Windows Update y modificar la versión del sistema operativo en la configuración del proyecto para un proyecto de código abierto.

Si una aserción devuelve "false" para indicar que el sistema no está en el estado deseado, se omitirá cualquier recurso que identifique esa aserción como una dependencia mediante el campo dependsOn y no se ejecutará. En este caso, aunque no se han aplicado cambios de configuración al entorno de Windows, esta configuración se consideraría un resultado correcto.

Sección resources

La lista de recursos abarca todo el software, las herramientas, los paquetes, etc., que deben instalarse, y las opciones de configuración para el sistema operativo Windows o las aplicaciones instaladas. Cada recurso deberá tener un nombre, una descripción de la directiva que se va a aplicar y el módulo de PowerShell que será responsable de hacerlo, así como cualquier configuración o dependencia asociadas.

Archivo de configuración de WinGet de ejemplo

A continuación se muestra un archivo configuración de WinGet de ejemplo con el formato configuration.dsc.yaml:

# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
properties:
  assertions:
    - resource: Microsoft.Windows.Developer/OsVersion
      directives:
        description: Verify min OS version requirement
        allowPrerelease: true
      settings:
        MinVersion: '10.0.22000'
  resources:
    - resource: Microsoft.Windows.Developer/DeveloperMode
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
      settings:
        Ensure: Present
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        allowPrerelease: true
      settings:
        id: Microsoft.VisualStudio.2022.Community
        source: winget
    - resource: Microsoft.VisualStudio.DSC/VSComponents
      dependsOn:
        - vsPackage
      directives:
        description: Install required VS workloads from vsconfig file
        allowPrerelease: true
      settings:
        productId: Microsoft.VisualStudio.Product.Community
        channelId: VisualStudio.17.Release
        vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
        includeRecommended: true
  configurationVersion: 0.2.0

Los componentes de este archivo son los siguientes:

Esquema: la primera línea del archivo de configuración debe contener el comentario # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #> para establecer el esquema DSC seguido del archivo. Para buscar la versión más reciente del esquema de configuración de WinGet, vaya a https://aka.ms/configuration-dsc-schema/. El número de esquema más reciente en el momento de este ejemplo es 0.2, por lo que el esquema se ha escrito como: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2.
Propiedades: el nodo raíz de un archivo de configuración es properties, que debe contener una versión de configuración (configurationVersion: 0.2.0 en este ejemplo). Esta versión se debe actualizar de acuerdo con las actualizaciones del archivo de configuración. El nodo properties debe contener un nodo assertions y un nodo resources.
Aserciones: en esta sección se enumeran las condiciones previas (o requisitos previos) necesarios para esta configuración.
Recursos: las secciones de lista assertions y resources constan de nodos resource individuales para representar la tarea de configuración. The resource should be given the name of the PowerShell module followed by the name of the module's DSC resource that will be invoked to apply your desired state: {ModuleName}/{DscResource}. Cada recurso debe incluir directives y settings. Opcionalmente, también puede incluir un valor de id. Al aplicar una configuración, WinGet sabrá instalar el módulo desde la Galería de PowerShell e invocar el recurso DSC especificado.
Directivas: la sección directives proporciona información sobre el módulo y el recurso. Esta sección debe incluir un valor description para describir la tarea de configuración que realiza el módulo. El valor allowPrerelease sirve para elegir si se permitirá (true) o no que la configuración use módulos "Versión preliminar" de la Galería de PowerShell.
Configuración: el valor settings de un recurso representa la colección de pares nombre-valor que se pasan al recurso de DSC de PowerShell. La configuración puede representar cualquier cosa, desde si el modo para desarrolladores está habilitado, la aplicación de una clave reg o el establecimiento de una configuración de red determinada.
Dependencias: el valor dependsOn de un recurso determina si cualquier otra aserción o recurso debe completarse antes de comenzar esta tarea. Si se produce un error en la dependencia, en este recurso también se producirá un error automáticamente.
ID: identificador único para la instancia de recurso determinada. El valor de id se puede usar si otro recurso tiene una dependencia de este recurso que se aplica primero.

Organización de la sección Recursos

Hay varios enfoques que se deben tener en cuenta al determinar cómo organizar la sección Recursos del archivo de configuración de WinGet. Puede organizar la lista de archivos por lo siguiente:

Orden de ejecución: la lista de recursos se organiza según el orden lógico en el que se deben ejecutar. Este enfoque puede ayudar al usuario a comprender y seguir los pasos de automatización que se realizan una vez que se ejecuta el archivo: lo que se instala primero, en segundo lugar, qué valor se actualiza en tercer lugar, etc.
Posibilidad de error: organizar la lista de recursos según la probabilidad de que se produzca un error potencial puede ayudar a los usuarios a detectar problemas al principio del proceso de configuración y a que comprendan por qué pueden producirse errores en los pasos restantes, lo que les permite identificar y realizar los cambios necesarios antes de invertir mucho tiempo.
Agrupación de tipos de recursos similares: organizar la lista de recursos mediante la agrupación de tipos de recursos similares es un enfoque común en las metodologías de ingeniería de software y puede ser el más familiar para usted o para otros desarrolladores que usan el archivo de configuración.

Se recomienda incluir un archivo README.md con cualquier archivo de configuración de WinGet publicado de código abierto que incluya el enfoque organizativo de la estructura de archivos.

Usar la variable ${WinGetConfigRoot}

Algunos recursos de DSC pueden tomar un parámetro que especifica la ruta de acceso de un archivo. En lugar de especificar la ruta de acceso completa, puede usar la variable ${WinGetConfigRoot} para definir el directorio de trabajo donde se ejecuta el comando winget configure y anexar la ruta de acceso relativa para que apunte a ese archivo. Esto es útil para generalizar un archivo de configuración para que sea independiente de la máquina. El recurso Microsoft.VisualStudio.DSC/VSComponents del ejemplo anterior muestra esta funcionalidad mediante el uso de ${WinGetConfigRoot} para apuntar a un archivo .vsconfig en el directorio raíz de un proyecto. Esto también significa que el usuario debe asegurarse de que el archivo de destino existe en la ruta de acceso relativa basada en el directorio de trabajo actual antes de ejecutar el comando winget configure.

Dónde buscar módulos de recursos de DSC de PowerShell

Consulte la lista de recursos de PowerShell listos para usar ("bandeja de entrada") Recursos Desired State Configuration admitidos por Microsoft, entre los que se incluyen los siguientes:

Environment: administre una variable de entorno para una máquina o un proceso.
MsiPackage: instale o desinstale un paquete MSI.
Registry: administre una clave o un valor del Registro.
Script: ejecute bloques de script de PowerShell.
Service: administre un servicio de Windows.
WindowsFeature: instale o desinstale un rol o característica de Windows.
WindowsProcess: inicie o detenga un proceso de Windows.

También puede encontrar módulos de recursos de DSC de PowerShell en la Galería de PowerShell. En esta galería se hospedan cientos de módulos de PowerShell que contienen recursos de Desired State Configuration (DSC) enviados por la comunidad de usuarios. Puede filtrar los resultados de la búsqueda si aplica el filtro "Recurso DSC" en "Categorías". Microsoft no comprueba este repositorio y contiene recursos de diversos autores y editores. Los módulos de PowerShell siempre se deben revisar para mejorar la seguridad y la credibilidad antes de usarse como cualquier scripting arbitrario. Vea Procedimiento para comprobar la confiabilidad de un archivo de configuración de WinGet para obtener más sugerencias sobre cómo crear un archivo de configuración de WinGet de confianza.

Compartir a través de