Erstellen einer WinGet-Konfigurationsdatei

Artikel
09/28/2023

So erstellen Sie eine WinGet-Konfigurationsdatei:

Erstellen Sie eine YAML-Datei gemäß der Konvention für die Benennung von WinGet-Konfigurationsdateien.
Machen Sie sich mit dem Format einer WinGet-Konfigurationsdatei vertraut, und verknüpfen Sie das aktuelle Dateischema.
Bestimmen Sie die Liste der Assertionen (erforderliche Vorbedingungen) und Ressourcen (Liste der erforderlichen Installationen und Einstellungskonfigurationen, um die Entwicklungsumgebung des Computers in den gewünschten Zustand zu bringen), die in die Datei aufgenommen werden sollen.
Identifizieren Sie die PowerShell-Module und Desired State Configuration (DSC)-Ressourcen, die zum Ausführen der gewünschten Konfigurationstasks erforderlich sind.
Bestimmen Sie die erforderlichen Direktiven und Einstellungen für jede Konfigurationsressource.
Bestimmen Sie die Abhängigkeiten für jede Ressource.

Erfahren Sie mehr über die Verwendung des WinGet-Konfigurationsbefehls.

Dateiformat

Windows-Paket-Manager verwendet Manifeste (YAML-Dateien), um Pakete für Windows-Benutzer zu suchen und zu installieren. WinGet-Konfigurationsdateien verwenden das gleiche YAML-Format, dem eine JSON-Schemaspezifikation zur Definition der Struktur und Validierung der Datei hinzugefügt wird. Zur weiteren Unterstützung bei der Erkennung, ob das Format Ihrer WinGet-Konfigurationsdatei gültig ist, empfehlen wir die Verwendung von Visual Studio Code mit der YAML-Erweiterung von RedHat, um die richtige Syntax zu unterstützen, Formatierungsfehler zu erkennen, Unterstützung beim Daraufzeigen sowie Autovervollständigung (bei Verknüpfung mit der JSON-Schemadatei) zu bieten und eine gültige Formatierung sicherzustellen.

Konventionen für die Dateibenennung

Die Konvention für die Benennung von WinGet-Konfigurationsdateien ist configuration.dsc.yaml. Für Git-basierte Projekte sollte die Standardkonfiguration in einem Verzeichnis „Konfigurationen“ unter ./configurations/configuration.dsc.yaml gespeichert werden.

Abschnitte einer WinGet-Konfigurationsdatei

Eine WinGet-Konfigurationsdatei ist in zwei primäre Abschnitte unterteilt:

Assertionen: Die Vorbedingungen, die zum Ausführen der Konfiguration erfüllt sein müssen.
Ressourcen: Die Liste der zu installierenden Software und Tools, die Konfigurationseinstellungen für diese Installationen und die Konfigurationseinstellungen für das Windows-Betriebssystem.

Abschnitt „Assertionen“

Die Liste der Assertionen deckt die Vorbedingungen (oder Voraussetzungen) ab, die erforderlich sind, damit die in dieser WinGet-Konfigurationsdatei aufgeführten Ressourcen auf dem Computer, auf dem die Datei ausgeführt wird, erfolgreich sind. Assertionen können parallel abgeschlossen werden und erfordern keine sequenzielle Reihenfolge.

Eine Beispielassertion:

Betriebssystemversion: Die Mindestversion des auf dem Computer installierten Betriebssystems*. Da dem Betriebssystem im Laufe der Zeit Features hinzugefügt werden, erfolgt für einige eine Rückportierung, um frühere Versionen zu unterstützen, für andere nicht. Es ist immer hilfreich, nach einer Mindestversion des Betriebssystems zu suchen, um zu ermitteln, ob ein bestimmtes für die Konfiguration erforderliches Tool oder Feature unterstützt wird. WinGet (Windows-Paket-Manager) erfordert beispielsweise mindestens Windows 10, Version 1809 oder höher. Alle älteren Versionen von Windows unterstützen WinGet nicht. *PowerShell DSC-Ressourcen können zwar den Zustand des Systems ändern, es wäre aber nicht angemessen, Windows Update aufzurufen und die Betriebssystemversion in der Projektkonfiguration für ein Open Source-Projekt zu ändern.

Wenn eine Assertion „false“ zurückgibt und damit anzeigt, dass sich das System nicht im gewünschten Zustand befindet, wird jede Ressource, die diese Assertion mithilfe des dependsOn-Felds als Abhängigkeit identifiziert, übersprungen und nicht ausgeführt. In diesem Fall wird diese Konfiguration als erfolgreiches Ergebnis betrachtet, obwohl keine Konfigurationsänderungen auf die Windows-Umgebung angewendet wurden.

Abschnitt "resources"

Die Liste der Ressourcen enthält die gesamte Software, alle Tools, Pakete usw., die installiert werden müssen, sowie die Konfigurationseinstellungen für Ihr Windows-Betriebssystem oder die installierten Anwendungen. Jeder Ressource müssen ein Name, eine Beschreibung der auszuführenden Direktive und das PowerShell-Modul, das für die Ausführung dieser Direktive verantwortlich ist, sowie alle zugehörigen Einstellungen oder Abhängigkeiten zugeordnet werden.

Beispiel für eine WinGet-Konfigurationsdatei

Im Folgenden wird eine Beispieldatei im WinGet-Konfigurationsformat configuration.dsc.yaml angezeigt:

# 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

Die Komponenten dieser Datei bestehen aus:

Schema: Die erste Zeile in Ihrer Konfigurationsdatei sollte den folgenden Kommentar enthalten: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #> zum Einrichten des DSC-Schemas, dem die Datei folgt. Um die neueste Version des WinGet-Konfigurationsschemas zu finden, wechseln Sie zu https://aka.ms/configuration-dsc-schema/. Die neueste Schemanummer zum Zeitpunkt dieses Beispiels ist 0.2, das Schema wurde also als # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2 eingegeben.
Eigenschaften: Der Stammknoten für eine Konfigurationsdatei ist properties und muss eine Konfigurationsversion enthalten (in diesem Beispiel configurationVersion: 0.2.0). Diese Version sollte entsprechend den Aktualisierungen der Konfigurationsdatei aktualisiert werden. Der Eigenschaften-Knoten sollte einen assertions-Knoten und einen resources-Knoten enthalten.
Assertionen: Listen Sie in diesem Abschnitt die für diese Konfiguration erforderlichen Vorbedingungen (oder Voraussetzungen) auf.
Ressourcen: Die Listenabschnitte assertions und resources bestehen aus einzelnen resource-Knoten, die den Einrichtungstask darstellen. Die resource sollte den Namen des PowerShell-Moduls enthalten, gefolgt von dem Namen der DSC-Ressource des Moduls, die aufgerufen wird, um den gewünschten Status anzuwenden: {ModuleName}/{DscResource}. Jede Ressource muss directives und settings enthalten. Optional kann sie auch einen id-Wert enthalten. Beim Anwenden einer Konfiguration weiß WinGet, dass das Modul aus der PowerShell-Galerie installiet und die angegebene DSC-Ressource aufgerufen werden muss.
Direktiven: Der Abschnitt directives enthält Informationen zum Modul und zur Ressource. Dieser Abschnitt sollte einen description-Wert enthalten, um den Konfigurationstask zu beschreiben, der vom Modul ausgeführt wird. Mit dem allowPrerelease-Wert können Sie auswählen, ob die Konfiguration „Vorabrelease“-Module aus dem PowerShell-Katalog verwenden darf (true) oder nicht.
Einstellungen: Der settings-Wert einer Ressource stellt die Sammlung von Name-Wert-Paaren dar, die an die PowerShell DSC-Ressource übergeben werden. Einstellungen können alles sein, von der Aktivierung des Entwicklermodus über die Anwendung eines Registrierungsschlüssels bis hin zur Festlegung einer bestimmten Netzwerkeinstellung.
Abhängigkeiten: Der dependsOn-Wert einer Ressource bestimmt, ob eine andere Assertion oder Ressource abgeschlossen sein muss, bevor dieser Task beginnt. Wenn die Abhängigkeit fehlgeschlagen ist, schlägt auch diese Ressource automatisch fehl.
ID: Ein eindeutiger Bezeichner für die jeweilige Ressourceninstanz. Der id-Wert kann verwendet werden, wenn eine andere Ressource davon abhängig ist, dass diese Ressource zuerst angewendet wird.

Organisieren des Ressourcen-Abschnitts

Bei der Bestimmung der Organisation des Ressourcen-Abschnitts Ihrer WinGet-Konfigurationsdatei sind mehrere Ansätze zu berücksichtigen. Sie können Ihre Dateiliste wie folgt organisieren:

Ausführungsreihenfolge: Organisieren der Ressourcenliste entsprechend der logischen Reihenfolge, in der sie ausgeführt werden sollen. Dieser Ansatz kann dem Benutzer helfen, die Automatisierungsschritte zu verstehen und nachzuvollziehen, die nach der Ausführung der Datei durchgeführt werden – was wird als erstes installiert, als zweites, welche Einstellung wird als drittes aktualisiert usw.
Fehlerwahrscheinlichkeit: Wenn Sie Ihre Ressourcenliste nach der Wahrscheinlichkeit eines möglichen Fehlers ordnen, können Sie den Benutzern helfen, Probleme frühzeitig im Konfigurationsprozess zu erkennen und zu verstehen, warum verbleibende Schritte fehlschlagen könnten. So können notwendige Änderungen vorgenommen werden, bevor viel Zeit investiert wird.
Gruppierung ähnlicher Ressourcentypen: Das Gruppieren Ihrer Ressourcenliste nach ähnlichen Ressourcentypen ist ein gängiger Ansatz in der Softwareentwicklung und dürfte Ihnen oder anderen Entwicklern, die Ihre Konfigurationsdatei verwenden, am besten vertraut sein.

Es wird empfohlen, zu jeder in Open Source veröffentlichten WinGet-Konfigurationsdatei eine README.md-Datei hinzuzufügen, die den organisationsbezogenen Ansatz der Dateistruktur enthält.

Verwenden der Variablen ${WinGetConfigRoot}

Bestimmte DSC-Ressourcen können einen Parameter enthalten, der den Pfad zu einer Datei angibt. Anstatt den vollständigen Pfad anzugeben, können Sie die Variable ${WinGetConfigRoot} verwenden, um das Arbeitsverzeichnis zu definieren, in dem der Befehl winget configure ausgeführt wird, und den relativen Pfad anhängen, um auf diese Datei zu verweisen. Dies ist nützlich, um eine Konfigurationsdatei so zu verallgemeinern, dass sie unabhängig vom Rechner ist. Die Ressource Microsoft.VisualStudio.DSC/VSComponents im obigen Beispiel zeigt diese Funktionalität, indem sie ${WinGetConfigRoot} verwendet, um auf eine .vsconfig-Datei im Stammverzeichnis eines Projekts zu verweisen. Das bedeutet auch, dass der Benutzer sicherstellen sollte, dass die Zieldatei unter dem relativen Pfad basierend auf dem aktuellen Arbeitsverzeichnis existiert, bevor er den Befehl winget configure ausführt.

Wo finde ich PowerShell DSC-Ressourcenmodule?

Sehen Sie sich die Liste der einsatzbereiten PowerShell-DSC-Ressourcen (Desired State Configuration) an, die von Microsoft unterstützt werden, beispielsweise:

Umgebung: Verwalten einer Umgebungsvariable für einen Computer oder Prozess.
MsiPackage: Installieren oder Deinstallieren eines MSI-Pakets.
Registrierung: Verwalten eines Registrierungsschlüssels oder -werts.
Skript: Ausführen von PowerShell-Skriptblöcken.
Dienst: Verwalten eines Windows-Diensts.
WindowsFeature: Installieren oder Deinstallieren einer Windows-Rolle oder eines Windows-Features.
WindowsProcess: Starten oder Beenden eines Windows-Prozesses.

Sie finden PowerShell DSC-Ressourcenmodule auch im PowerShell-Katalog. Dieser Katalog hostet Hunderte von PowerShell-Modulen mit von der Benutzercommunity übermittelten DSC-Ressourcen (Desired State Configuration). Sie können Suchergebnisse filtern, indem Sie den Filter „DSC-Ressource“ unter „Kategorien“ anwenden. Dieses Repository wird nicht von Microsoft überprüft und enthält Ressourcen von einer Vielzahl von Autoren und Herausgebern. PowerShell-Module sollten immer vor der Verwendung auf Sicherheit und Glaubwürdigkeit überprüft werden, da jegliche Art von Skripts enthalten sein können. Weitere Tipps zum Erstellen einer vertrauenswürdigen WinGet-Konfigurationsdatei finden Sie unter Überprüfen der Vertrauenswürdigkeit einer WinGet-Konfigurationsdatei.

Share via