Création d’un fichier de configuration WinGet

2025-05-05

Pour créer un fichier de configuration WinGet :

Créez un fichier YAML suivant la convention d’affectation de noms de fichier 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 (liste des installations et configurations de paramètre requises pour obtenir l’environnement de développement de l’ordinateur à l’état souhaité) à inclure dans le fichier.
Identifiez les modules PowerShell et les ressources DSC (Desired State Configuration) nécessaires pour accomplir vos 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.

En savoir plus sur l’utilisation de la commande De configuration WinGet.

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 vous aider à définir la structure et la validation du fichier. Pour mieux 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 une prise en charge du pointage et une saisie semi-automatique (lorsqu’il est lié au fichier de schéma JSON) et garantir une mise en forme valide.

Convention d’affectation de noms de fichiers

La convention de nommage d’un fichier de configuration WinGet utilise l’extension de fichier .winget (par exemple configuration.winget). Pour les projets Git, la configuration par défaut doit être stockée dans un répertoire «.config» à l’adresse : ./config/configuration.winget. Dans certains cas, plusieurs fichiers de configuration peuvent être appropriés en fonction de différentes chaînes d’outils ou préférences utilisateur. Ces fichiers de configuration supplémentaires doivent également se trouver dans le répertoire «.config».

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 : liste des logiciels et des outils à installer, les paramètres de configuration de ces installations et les paramètres de configuration du système d’exploitation Windows.

Assertions de la Section

La liste des assertions couvre les conditions préalables (ou conditions préalables) requises pour les ressources répertoriées dans ce fichier de configuration WinGet pour réussir 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 les 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 et certaines ne le sont pas. Il est toujours utile de rechercher une version minimale du système d’exploitation pour déterminer si un outil ou une fonctionnalité spécifique peut être pris en charge pour la configuration. Par exemple, WinGet (Gestionnaire de package Windows) nécessite un minimum de Windows 10, version 1809 ou ultérieure. Toutes les versions antérieures de Windows ne prennent pas en charge WinGet. * Il est possible que les ressources DSC PowerShell modifient l’état du système, mais il ne convient pas 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 comme dépendance à l’aide du dependsOn champ est ignorée et ne peut 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 avoir 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 de tous les paramètres ou dépendances associés.

Exemple de fichier de configuration WinGet

Voici un exemple de fichier de configuration WinGet 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

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 par le 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, donc 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 doit properties 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 assertions nœud et un resources nœud.
Assertions: répertoriez les conditions préalables (ou conditions préalables) requises pour cette configuration dans cette section.
Ressources : les sections assertions et resources sont constituées de nœuds individuels resource 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 id valeur. Lors de l’application d’une configuration, WinGet sait installer le module à partir du PowerShell Gallery et appeler la ressource DSC spécifiée.
Directives : La directives section fournit des informations sur le module et la ressource. Cette section doit inclure une description valeur pour décrire la tâche de configuration effectuée par le module. La valeur allowPrerelease vous permet de choisir si oui ou non la configuration sera autorisée (true) à utiliser des modules « Préversion » depuis la PowerShell Gallery. Certaines ressources DSC peuvent avoir besoin d’être exécutées avec des privilèges d’administrateur. Le securityContext: elevated champ sous la section directives d’une ressource indique cette exigence. Lorsque la valeur est définie elevated, WinGet demande une approbation UAC au début de la configuration. WinGet lance ensuite deux processus : une qui exécute des ressources avec des privilèges élevés et une autre qui exécute des ressources avec les privilèges de l’utilisateur actuel.
Settings: la valeur settings d’une ressource indique l'ensemble des paires nom-valeur passées à la ressource DSC PowerShell. Les paramètres peuvent représenter quoi que ce soit, qu’il s’agisse du mode développeur activé, de l’application d’une clé reg ou de l’établissement d’un paramètre réseau particulier.
Dépendances : la dependsOn valeur d’une ressource détermine si une 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 pour l’instance de ressource particulière. La id valeur 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 par :

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 en cours d’exécution une fois le fichier exécuté : ce qui est installé en premier, deuxième, quel paramètre est mis à jour troisième, etc.
Possibilité d’échec : l’organisation de votre liste de ressources en fonction de la probabilité d’un échec potentiel peut aider les utilisateurs à détecter les problèmes au 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 d’investir beaucoup de temps.
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 d’ingénierie logicielle 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é 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 winget configure commande 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 Microsoft.VisualStudio.DSC/VSComponents ressource de l’exemple ci-dessus présente cette fonctionnalité en utilisant le ${WinGetConfigRoot} pour indiquer un fichier .vsconfig dans le répertoire racine d’un projet. Cela signifie également que 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 winget configure commande.

Où trouver des modules de ressources DSC PowerShell

Consultez la liste des ressources de configuration d’état souhaitées powerShell prêtes à l’emploi (« boîte de réception ») prises en charge par Microsoft, notamment :

Environnement : gérez une variable d’environnement pour un ordinateur 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érer un service Windows.
WindowsFeature : installez ou désinstallez un rôle ou une fonctionnalité Windows.
WindowsProcess : Démarrez ou arrêtez un processus Windows.

Vous pouvez également trouver des modules de ressources DSC dans la PowerShell Gallery. Cette galerie héberge des centaines de modules PowerShell contenant des ressources DSC (Desired State Configuration) soumises par la communauté des utilisateurs. Vous pouvez filtrer les résultats de la recherche en appliquant le filtre « Ressource DSC » sous « Catégories ». Ce référentiel n’est pas vérifié par Microsoft et contient des ressources provenant de divers auteurs et éditeurs. Les modules PowerShell doivent toujours être examinés pour la sécurité et la crédibilité avant d’être utilisés comme tout script arbitraire peut être inclus. Découvrez comment vérifier la fiabilité d’un fichier de configuration WinGet pour obtenir des conseils supplémentaires sur la création d’un fichier de configuration WinGet fiable.