Compartir a través de

Cómo crear un archivo de configuración de WinGet

Para crear un archivo de configuración de WinGet:

  1. Cree un archivo YAML siguiendo la convención de nomenclatura de archivos de configuración de WinGet .
  2. Familiarícese con el formato de un archivo de configuración de WinGet y vincule el esquema de archivo actual .
  3. Determine la lista de Aserciones (condiciones previas necesarias) y Recursos (la lista de instalaciones necesarias y configuraciones para configurar el entorno de desarrollo del equipo al estado deseado) para incluir en el archivo.
  4. Identifique los módulos de PowerShell y los recursos de Desired State Configuration (DSC) necesarios para realizar las tareas de configuración deseadas.
  5. Determine las directivas y la configuración necesarias para cada recurso de configuración.
  6. Determine las dependencias de cada recurso.

Obtenga más información sobre el uso del comando Configurar winGet.

Formato de archivo

El Administrador de paquetes de Windows usa manifiestos (archivos YAML) para buscar e instalar paquetes para usuarios de Windows. Los archivos de configuración de WinGet usan el mismo formato de estilo YAML, agregando una especificación de esquema JSON para ayudar a definir la estructura y la validación del archivo. Para ayudar a detectar aún más 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 puntero y finalización automática (cuando esté vinculado al archivo de esquema JSON) y garantizar el formato válido.

Convención de nomenclatura de archivos

La convención para asignar un nombre a un archivo de configuración de WinGet usa la extensión de archivo ".winget" (como configuration.winget). Para los proyectos basados en Git, la configuración predeterminada debe almacenarse en un directorio ".config" en: ./config/configuration.winget. En algunos casos, es posible que más de un archivo de configuración sea adecuado dadas diferentes cadenas de herramientas o preferencias de usuario. Esos archivos de configuración adicionales también deben encontrarse en el directorio ".config".

Secciones de un archivo de configuración de WinGet

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

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

Sección Aserciones

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

Una aserción de ejemplo:

  • versión del sistema operativo: una versión mínima del sistema operativo* instalada en la máquina. A medida que se agregan características a lo largo del tiempo al sistema operativo, algunas se vuelven a importar para admitir versiones anteriores y algunas 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 que sea necesaria para la configuración. Por ejemplo, WinGet (Administrador de paquetes de Windows) requiere un mínimo de 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, cualquier recurso que identifique esa aserción como una dependencia mediante el campo dependsOn se pasará por alto y no se ejecutará. En este caso, aunque no se aplicaron cambios de configuración al entorno de Windows, esta configuración se consideraría un resultado correcto.

Sección Recursos

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 llevar a cabo y el módulo de PowerShell que será responsable de llevar a cabo esa directiva, así como cualquier configuración o dependencia asociada.

Archivo de configuración de WinGet de ejemplo

A continuación se muestra un archivo de configuración de WinGet formateado como ejemplo configuration.winget:

# 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.Settings/WindowsSettings
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
        securityContext: elevated
      settings:
        DeveloperMode: true
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        securityContext: elevated
      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
        securityContext: elevated
      settings:
        productId: Microsoft.VisualStudio.Product.Community
        channelId: VisualStudio.17.Release
        vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
        includeRecommended: true
  configurationVersion: 0.2.0

Los componentes de este archivo constan de:

  1. esquema: la primera línea del archivo de configuración debe contener el comentario siguiente: # 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 especificó como: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2.

  2. Propiedades: el nodo raíz de un archivo de configuración es properties el que debe contener una versión de configuración (configurationVersion: 0.2.0 en este ejemplo). Esta versión debe actualizarse de acuerdo con las actualizaciones del archivo de configuración. El nodo properties debe contener un assertions nodo y un resources nodo.

  3. Aserciones: enumere las condiciones previas (o requisitos previos) necesarios para esta configuración en esta sección.

  4. Recursos: las secciones assertions y resources de lista constan de nodos individuales resource para representar la tarea de configuración. El resource debe tener el nombre del módulo de PowerShell seguido del nombre del recurso de DSC del módulo que se invocará para aplicar el estado deseado: {ModuleName}/{DscResource}. Cada recurso debe incluir directives y settings. Opcionalmente, también puede incluir un id valor. Al aplicar una configuración, WinGet sabrá instalar el módulo desde Galería de PowerShell e invocar el recurso de DSC especificado .

  5. Directivas: la sección directives proporciona información sobre el módulo y el recurso. Esta sección debe incluir un valor de description para describir la tarea de configuración que realiza el módulo. El valor de allowPrerelease te permite elegir si se permitirá o no que la configuracióntrueuse módulos de "versión preliminar" de la PowerShell Gallery . Es posible que algunos recursos de DSC necesiten ejecutarse con privilegios de administrador. El securityContext: elevated campo de la sección directivas de un recurso indica este requisito. Cuando se establece en elevated, WinGet solicitará una aprobación de UAC al principio de la configuración. A continuación, WinGet iniciará dos procesos: uno que ejecuta recursos con privilegios elevados y otro que ejecuta recursos con los privilegios del usuario actual.

  6. 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 podría representar cualquier cosa desde si el modo de desarrollador está habilitado, para aplicar una clave regular o para establecer una configuración de red determinada.

  7. Dependencias: el valor dependsOn de un recurso determina si cualquier otra aserción o recurso debe completarse antes de comenzar esta tarea. Si se produjo un error en la dependencia, este recurso también producirá un error automáticamente.

  8. ID: un identificador único para la instancia de recurso determinada. El id valor 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 mediante:

  • orden de ejecución: organización de la lista de recursos 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, segundo, qué configuración se actualiza en tercer lugar, etc.
  • posibilidad de error: organizar la lista de recursos de acuerdo con la probabilidad de un posible error puede ayudar a los usuarios a detectar problemas al principio del proceso de configuración y ayudarles a comprender por qué pueden producirse errores en los pasos restantes, lo que les permite identificar y realizar 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 aceptar un parámetro que especifica la ruta 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 del ${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 configuración de estado deseado de PowerShell listos para usar ("bandeja de entrada") compatibles con Microsoft, incluidos:

  • Entorno: administre una variable de entorno para una máquina o proceso.
  • msiPackage: instale o desinstale un paquete MSI.
  • Registro: Gestionar una clave o valor del Registro.
  • script: ejecute bloques de script de PowerShell.
  • Service: administrar un servicio de Windows.
  • WindowsFeature: instale o desinstale un rol o función de Windows.
  • WindowsProcess: iniciar o detener un proceso de Windows.

También puede encontrar módulos de recursos de DSC de PowerShell en la Galería de PowerShell de . Esta galería hospeda 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 aplicando el filtro "Recurso DSC" en "Categorías". Este repositorio no está verificado por Microsoft y contiene recursos de varios autores y editores. Los módulos de PowerShell siempre deben revisarse para seguridad y credibilidad antes de ser utilizados, ya que cualquier scripting arbitrario puede incluirse. Consulta Cómo 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.