Comment créer un fichier de configuration WinGet

Article
09/28/2023

Pour créer un fichier de configuration WinGet :

Créez un fichier YAML en suivant la convention d’affectation de noms de fichier de configuration WinGet.
Familiarisez-vous avec le format d’un fichier de configuration WinGet et liez le schéma de fichier actuel.
Déterminez la liste des assertions (conditions préalables requises) et des ressources (la liste des installations requises et des configurations de paramètres pour obtenir l’environnement de développement de l’ordinateur à l’état souhaité) à inclure dans le fichier.
Identifiez les modules PowerShell et les ressources de Desired State Configuration (DSC) nécessaires pour accomplir les tâches de configuration souhaitées.
Déterminez les directives et les paramètres nécessaires pour chaque ressource de configuration.
Déterminez les dépendances pour chaque ressource.

Apprenez-en davantage sur l’utilisation de la commande WinGet configure.

Format de fichier

Le Gestionnaire de package Windows utilise des manifestes (fichiers YAML) pour localiser et installer des packages pour les utilisateurs Windows. Les fichiers de configuration WinGet utilisent le même format de style YAML, en ajoutant une spécification de schéma JSON pour aider à définir la structure et la validation du fichier. Pour vous aider à détecter si le format de votre fichier de configuration WinGet est valide, nous vous recommandons d’utiliser Visual Studio Code avec l’extension YAML de RedHat pour prendre en charge la syntaxe appropriée, détecter les erreurs de mise en forme, fournir la prise en charge du pointage et l’autocomplétion (lorsqu’elle est liée au fichier de schéma JSON), et garantir une mise en forme valide.

Conventions d’affectation de noms de fichier

La convention pour nommer un fichier de configuration WinGet est configuration.dsc.yaml. Pour les projets basés sur Git, la configuration par défaut doit être stockée dans un répertoire « configurations » à l’adresse : ./configurations/configuration.dsc.yaml.

Sections d’un fichier de configuration WinGet

Un fichier de configuration WinGet est séparé en deux sections principales :

Assertions : conditions préalables requises pour exécuter la configuration.
Ressources : la liste des logiciels et outils à installer, les paramètres de configuration de ces installations et les paramètres de configuration du système d’exploitation Windows.

Section Assertions

La liste des assertions couvre les conditions préalables (ou prérequis) requises pour que les ressources répertoriées dans ce fichier de configuration WinGet réussissent sur l’ordinateur exécutant le fichier. Les assertions peuvent être effectuées en parallèle et ne nécessitent aucun ordre séquentiel.

Exemple d’assertion :

Version du système d’exploitation : version minimale du système d’exploitation* installée sur l’ordinateur. Comme des fonctionnalités sont ajoutées au fil du temps au système d’exploitation, certaines sont rétroportées pour prendre en charge les versions antérieures, tandis que d’autres ne le sont pas. Il est toujours utile de vérifier si vous avez la version minimale du système d’exploitation afin de déterminer si un outil ou une fonctionnalité spécifique nécessaire à la configuration peut être pris en charge. Par exemple, WinGet (Gestionnaire de package Windows) nécessite un minimum de Windows 10, version 1809 ou plus récent. Les versions antérieures de Windows ne prennent pas en charge WinGet. *Il est possible pour les ressources DSC PowerShell de modifier l’état du système, mais il ne serait pas approprié d’appeler Windows Update et de modifier la version du système d’exploitation dans la configuration du projet pour un projet open source.

Si une assertion retourne « false » pour indiquer que le système n’est pas dans l’état souhaité, toute ressource identifiant cette assertion en tant que dépendance à l’aide du champ dependsOn sera ignorée et ne pourra pas s’exécuter. Dans ce cas, même si aucune modification de configuration n’a été appliquée à l’environnement Windows, cette configuration serait considérée comme un résultat réussi.

Section Ressources

La liste des ressources couvre tous les logiciels, outils, packages, etc. qui doivent être installés et les paramètres de configuration de votre système d’exploitation Windows ou des applications installées. Chaque ressource doit recevoir un nom, une description de la directive à exécuter et le module PowerShell qui sera responsable de l’exécution de cette directive, ainsi que tous les paramètres ou dépendances associés.

Exemple de fichier de configuration WinGet

Voici un exemple de fichier au format WinGet Configuration 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

Les composants de ce fichier se composent des éléments suivants :

Schéma : la première ligne de votre fichier de configuration doit contenir le commentaire suivant : # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #> pour établir le schéma DSC suivi du fichier. Pour trouver la version la plus récente du schéma de configuration WinGet, accédez à https://aka.ms/configuration-dsc-schema/. Le numéro de schéma le plus récent au moment de cet exemple est 0.2, de sorte que le schéma a été entré comme suit : # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2.
Propriétés : le nœud racine d’un fichier de configuration est properties qui doit contenir une version de configuration (configurationVersion: 0.2.0 dans cet exemple). Cette version doit être mise à jour conformément aux mises à jour apportées au fichier de configuration. Le nœud de propriétés doit contenir un nœud assertions et un nœud resources.
Assertions : répertoriez les conditions préalables (ou prérequis) requises pour cette configuration dans cette section.
Ressources : les sections assertions et resources sont constituées de nœuds resource individuels pour représenter la tâche de configuration. La ressource resource doit avoir le nom du module PowerShell suivi du nom de la ressource DSC du module qui sera appelée pour appliquer l’état souhaité : {ModuleName}/{DscResource}. Chaque ressource doit inclure directives et settings. Si vous le souhaitez, il peut également inclure une valeur id. Lors de l’application d’une configuration, WinGet sait installer le module à partir de PowerShell Gallery et appeler la ressource DSC spécifiée.
Directives : la section directives fournit des informations sur le module et la ressource. Cette section doit également inclure une valeur description pour décrire la tâche de configuration effectuée par le module. La valeur allowPrerelease vous permet de choisir si la configuration sera autorisée (true) à utiliser les modules « Préversion » de la galerie PowerShell.
Paramètres : la valeur settings d’une ressource représente la collection de paires nom-valeur passées à la ressource PowerShell DSC. Les paramètres peuvent représenter n’importe quel élément, qu’il s’agisse de l’activation du mode développeur, de l’application d’une clé reg ou de l’établissement d’un paramètre réseau particulier.
Dépendances : la valeur dependsOn d’une ressource détermine si toute autre assertion ou ressource doit être terminée avant de commencer cette tâche. Si la dépendance a échoué, cette ressource échoue également automatiquement.
ID : identificateur unique de l’instance de la ressource particulière. La valeur id peut être utilisée si une autre ressource a une dépendance sur cette ressource appliquée en premier.

Organisation de la section Ressources

Il existe plusieurs approches à prendre en compte pour déterminer comment organiser la section Ressources de votre fichier de configuration WinGet. Vous pouvez organiser votre liste de fichiers en :

Ordre d’exécution : organisation de votre liste de ressources en fonction de l’ordre logique dans lequel elles doivent être exécutées. Cette approche peut aider l’utilisateur à comprendre et à suivre les étapes d’automatisation effectuées une fois le fichier exécuté : ce qui est installé en premier, en deuxième, quel paramètre est mis à jour en troisième, etc.
Possibilité d’échec : l’organisation de votre liste de ressources en fonction de la probabilité d’une défaillance potentielle peut aider les utilisateurs à détecter les problèmes dès le début du processus de configuration et à comprendre pourquoi les étapes restantes peuvent échouer, ce qui leur permet d’identifier et d’apporter les modifications nécessaires avant que beaucoup de temps ne soit investi.
Regroupement de types de ressources similaires : l’organisation de votre liste de ressources en regroupant des types de ressources similaires est une approche courante dans les méthodologies de génie logiciel et peut être la plus familière à vous ou à d’autres développeurs qui utilisent votre fichier de configuration.

Nous vous recommandons d’inclure un fichier README.md avec n’importe quel fichier de configuration WinGet publié en open source qui inclut l’approche organisationnelle de la structure de fichiers.

Utilisation de la variable ${WinGetConfigRoot}

Certaines ressources DSC peuvent prendre un paramètre qui spécifie le chemin d’accès d’un fichier. Au lieu de spécifier le chemin d’accès complet, vous pouvez utiliser la variable ${WinGetConfigRoot} pour définir le répertoire de travail dans lequel la commande winget configure est exécutée et ajouter le chemin relatif pour pointer vers ce fichier. Cela est utile pour généraliser un fichier de configuration afin qu’il soit indépendant de l’ordinateur. La ressource Microsoft.VisualStudio.DSC/VSComponents dans l’exemple ci-dessus présente cette fonctionnalité en utilisant ${WinGetConfigRoot} pour pointer vers un fichier .vsconfig dans le répertoire racine d’un projet. De plus, l’utilisateur doit s’assurer que le fichier cible existe au niveau du chemin d’accès relatif en fonction du répertoire de travail actuel avant d’exécuter la commande winget configure.

Où trouver les modules de ressources PowerShell DSC

Consultez la liste des ressources de Desired State Configuration PowerShell prêtes à l’emploi (« boîte de réception ») prises en charge par Microsoft, notamment :

Environnement : gérer une variable d’environnement pour une machine ou un processus.
MsiPackage : installez ou désinstallez un package MSI.
Registre : gérez une clé ou une valeur de Registre.
Script : exécutez des blocs de script PowerShell.
Service : gérez un service Windows.
WindowsFeature : installer ou désinstaller un rôle ou une fonctionnalité Windows.
WindowsProcess : démarrer ou arrêter un processus Windows.

Vous pouvez également trouver des modules de ressources PowerShell DSC dans la galerie PowerShell. Cette galerie héberge des centaines de modules PowerShell contenant des ressources Desired State Configuration (DSC) soumises par la communauté d’utilisateurs. Vous pouvez filtrer les résultats de la recherche en appliquant le filtre « Ressource DSC » sous « Catégories ». Ce dépôt n’est pas vérifié par Microsoft et contient des ressources provenant de divers auteurs et éditeurs qui ne doivent pas être approuvés par défaut. Les modules PowerShell doivent toujours être examinés à des fins de sécurité et de crédibilité avant d’être utilisés, car tout script arbitraire peut être inclus. Pour plus d’informations sur la création d’un fichier de configuration WinGet digne de confiance, consultez Guide pratique pour vérifier la fiabilité d’un fichier de configuration WinGet.