Freigeben über

Wie man eine WinGet-Konfigurationsdatei erstellt

So erstellen Sie eine WinGet-Konfigurationsdatei:

  1. Erstellen Sie eine YAML-Datei nach der WinGet-Konfiguration Dateibenennungskonvention.
  2. Machen Sie sich mit dem Format einer WinGet-Konfigurationsdatei vertraut und verknüpfen Sie das aktuelle Dateischema.
  3. Ermitteln Sie die Liste der Assertionen (erforderliche Voraussetzungen) und Ressourcen (die Liste der erforderlichen Installationen und Einstellungskonfigurationen, um die Entwicklungsumgebung des Computers in den gewünschten Zustand zu bringen), um sie in die Datei aufzunehmen.
  4. Identifizieren Sie die PowerShell-Module und die erforderlichen DSC-Ressourcen (Desired State Configuration), um Ihre gewünschten Konfigurationsaufgaben auszuführen.
  5. Bestimmen Sie die für jede Konfigurationsressource erforderlichen Direktiven und Einstellungen.
  6. Bestimmen Sie die Abhängigkeiten für jede Ressource.

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

Dateiformat

Der Windows-Paket-Manager verwendet Manifeste (YAML-Dateien), um Pakete für Windows-Benutzer zu suchen und zu installieren. WinGet-Konfigurationsdateien verwenden dasselbe YAML-Format und fügen eine JSON-Schemaspezifikation hinzu, um die Struktur und Validierung der Datei zu definieren. Um weiter zu helfen, zu erkennen, ob das Format Ihrer WinGet-Konfigurationsdatei gültig ist, empfehlen wir, Visual Studio Code mit der YAML-Erweiterung von RedHat zu verwenden, um die richtige Syntax zu unterstützen, Formatierungsfehler zu erkennen, Hover-Unterstützung und autovervollständigen (wenn mit der JSON-Schemadatei verknüpft) bereitzustellen und gültige Formatierungen sicherzustellen.

Benennungskonvention für Dateien

Die Konvention zum Benennen einer WinGet-Konfigurationsdatei verwendet die Dateierweiterung ".winget" (z. B configuration.winget. ). Bei Git-basierten Projekten sollte die Standardkonfiguration in einem Verzeichnis ".config" unter: gespeichert werden. ./config/configuration.winget In einigen Fällen sind möglicherweise mehrere Konfigurationsdateien mit unterschiedlichen Toolketten oder Benutzereinstellungen geeignet. Diese zusätzlichen Konfigurationsdateien sollten sich auch im Verzeichnis ".config" befinden.

Abschnitte einer WinGet-Konfigurationsdatei

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

  1. Assertionen: Die zum Ausführen der Konfiguration erforderlichen Voraussetzungen.
  2. Ressourcen: Die Liste der zu installierenden Software und Tools, die Konfigurationseinstellungen für diese Installationen und die Konfigurationseinstellungen für das Windows-Betriebssystem.

Annahmen-Abschnitt

Die Liste der Assertionen deckt die Voraussetzungen (oder Vorbedingungen) ab, die für die in dieser WinGet-Konfigurationsdatei aufgeführten Ressourcen erforderlich sind, um erfolgreich auf dem Rechner ausgeführt zu werden, auf dem die Datei läuft. Assertionen können parallel abgeschlossen werden und erfordern keine sequenzielle Reihenfolge.

Beispiel für eine Behauptung:

  • Betriebssystemversion: Eine Mindestversion des Betriebssystems*, die auf der Maschine installiert werden muss. Da im Laufe der Zeit Funktionen zum Betriebssystem hinzugefügt werden, werden einige zurückportiert, um frühere Versionen zu unterstützen, und einige nicht zurückportiert. Es ist immer hilfreich, nach einer Mindestversion des Betriebssystems zu suchen, um zu ermitteln, ob ein bestimmtes Tool oder Feature unterstützt werden kann, das für die Konfiguration erforderlich ist. Beispielsweise erfordert WinGet (Windows Package Manager) mindestens Windows 10, Version 1809 oder höher. Alle älteren Versionen von Windows unterstützen WinGet nicht. * Es ist möglich, dass PowerShell DSC-Ressourcen den Status des Systems ändern, aber es wäre nicht sinnvoll, Windows Update aufzurufen und die Betriebssystemversion in der Projektkonfiguration für ein Open-Source-Projekt zu ändern.

Wenn eine Assertion "false" zurückgibt, was darauf hinweist, dass sich das System nicht im gewünschten Zustand befindet, wird jede Ressource, die diese Assertion als Abhängigkeit mit dem Feld dependsOn identifiziert, übersprungen und nicht ausgeführt werden. In diesem Fall gilt diese Konfiguration auch dann, wenn keine Konfigurationsänderungen auf die Windows-Umgebung angewendet wurden, als erfolgreiches Ergebnis.

Abschnitt "Ressourcen"

Die Liste der Ressourcen umfasst alle Software, Tools, Pakete usw., die installiert werden müssen, sowie die Konfigurationseinstellungen für Ihr Windows-Betriebssystem oder installierte Anwendungen. Jede Ressource muss einen Namen, eine Beschreibung der auszuführenden Direktive und das PowerShell-Modul erhalten, das für die Ausführung dieser Richtlinie sowie für alle zugehörigen Einstellungen oder Abhängigkeiten verantwortlich ist.

Beispiel-WinGet-Konfigurationsdatei

Im Folgenden sehen Sie ein Beispiel für eine im WinGet-Konfigurationsformat configuration.winget formatierte Datei:

# 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

Die Komponenten dieser Datei bestehen aus:

  1. Schema-: Die erste Zeile in der Konfigurationsdatei sollte den folgenden Kommentar enthalten: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #>, um festzulegen, welches DSC-Schema die Datei verfolgt. 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 lautet 0.2, sodass das Schema als: eingegeben wurde. # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2

  2. Eigenschaften: Der Stammknoten für eine Konfigurationsdatei muss properties eine Konfigurationsversion enthalten (configurationVersion: 0.2.0 in diesem Beispiel). Diese Version sollte entsprechend den Aktualisierungen der Konfigurationsdatei aktualisiert werden. Der Eigenschaftenknoten sollte einen assertions Knoten und einen resources Knoten enthalten.

  3. Assertions: Listet die für diese Konfiguration erforderlichen Voraussetzungen in diesem Abschnitt auf.

  4. Ressourcen: Sowohl die assertions- als auch die resources-Listenabschnitte bestehen aus einzelnen resource Knoten, die die Einrichtung der Aufgabe darstellen. Der resource muss den Namen des PowerShell-Moduls haben, gefolgt vom Namen der DSC-Ressource des Moduls, die aufgerufen wird, um den gewünschten Zustand anzuwenden: {ModuleName}/{DscResource}. Jede Ressource muss enthalten directives und settings. Optional kann er auch einen id Wert enthalten. Beim Anwenden einer Konfiguration weiß WinGet, das Modul aus der PowerShell Gallery zu installieren und die angegebene DSC-Ressourceaufzurufen.

  5. Richtlinien: Der Abschnitt directives enthält Informationen zum Modul und zur Ressource. Dieser Abschnitt sollte einen description Wert enthalten, um die vom Modul ausgeführte Konfigurationsaufgabe zu beschreiben. Mit dem Wert allowPrerelease können Sie auswählen, ob die Konfiguration (true) die Verwendung von "Prerelease"-Modulen aus der PowerShell-Galeriezulässt. Einige DSC-Ressourcen müssen möglicherweise mit Administratorrechten ausgeführt werden. Das securityContext: elevated Feld unter dem Direktivenabschnitt einer Ressource gibt diese Anforderung an. Bei Festlegung auf elevated" fordert WinGet am Anfang der Konfiguration eine UAC-Genehmigung auf. WinGet startet dann zwei Prozesse: eine, die Ressourcen mit erhöhten Rechten ausführt und eine andere, die Ressourcen mit den Berechtigungen des aktuellen Benutzers ausführt.

  6. Einstellungen: Der settings Wert einer Ressource stellt die Auflistung von Name-Wert-Paaren dar, die an die PowerShell DSC-Ressource übergeben werden. Einstellungen können jegliche Einstellung umfassen, von der Aktivierung des Entwicklermodus über die Anwendung eines Registrierungsschlüssels bis hin zur Einrichtung einer bestimmten Netzwerkeinstellung.

  7. Abhängigkeiten: Der dependsOn-Wert einer Ressource bestimmt, ob eine andere Assertion oder Ressource vor Beginn dieses Vorgangs vollständig sein muss. Wenn die Abhängigkeit fehlgeschlagen ist, schlägt diese Ressource ebenfalls automatisch fehl.

  8. ID: Eine eindeutige Kennung für die jeweilige Ressource. Der id Wert kann verwendet werden, wenn eine andere Ressource davon abhängt, dass diese Ressource zuerst angewendet wird.

Organisieren des Abschnitts "Ressourcen"

Es gibt mehrere Ansätze, die Sie berücksichtigen sollten, wenn Sie bestimmen, wie der Abschnitt "Ressourcen" der WinGet-Konfigurationsdatei organisiert wird. Sie können Ihre Liste der Dateien organisieren, indem Sie:

  • Ausführungsreihenfolge: Organisieren Sie Ihre Ressourcenliste entsprechend der logischen Reihenfolge, in der sie ausgeführt werden sollen. Dieser Ansatz kann dem Benutzer helfen, die Automatisierungsschritte zu verstehen und zu befolgen, die ausgeführt werden, sobald die Datei ausgeführt wird – was zuerst installiert wird, zweitens, welche Einstellung drittens aktualisiert wird usw.
  • Möglichkeit eines Fehlers: Das Organisieren Ihrer Ressourcenliste gemäß der Wahrscheinlichkeit eines potenziellen Fehlers kann Benutzern helfen, Probleme frühzeitig im Konfigurationsprozess zu erfassen und zu verstehen, warum verbleibende Schritte fehlschlagen können, sodass sie notwendige Änderungen identifizieren und vornehmen können, bevor viel Zeit investiert wird.
  • Gruppieren ähnlicher Ressourcentypen: Das Organisieren ihrer Ressourcenliste durch Gruppieren ähnlicher Ressourcentypen ist ein gängiger Ansatz in Software engineering-Methoden und kann Ihnen oder anderen Entwicklern, die Ihre Konfigurationsdatei verwenden, am vertrautsten sein.

Es wird empfohlen, eine README.md Datei in jede veröffentlichte Open Source WinGet-Konfigurationsdatei einzufügen, die die organisatorische Herangehensweise der Dateistruktur enthält.

Verwenden der Variablen ${WinGetConfigRoot}

Bestimmte DSC-Ressourcen können einen Parameter annehmen, der den Pfad einer Datei angibt. Anstatt den vollständigen Pfad anzugeben, können Sie die Variable ${WinGetConfigRoot} verwenden, um das Arbeitsverzeichnis zu definieren, in dem der winget configure Befehl ausgeführt wird, und den relativen Pfad hinzufügen, um auf diese Datei zu verweisen. Dies ist nützlich für die Generalisierung einer Konfigurationsdatei, sodass sie computeragnostisch ist. Die Microsoft.VisualStudio.DSC/VSComponents Ressource im obigen Beispiel zeigt diese Funktionalität, indem die ${WinGetConfigRoot} verwendet wird, um auf eine .vsconfig-Datei im Stammverzeichnis eines Projekts zu verweisen. Dies bedeutet auch, dass der Benutzer sicherstellen muss, dass die Zieldatei im relativen Pfad zum aktuellen Arbeitsverzeichnis vorhanden ist, bevor der Befehl winget configureausgeführt wird.

Wo finden Sie PowerShell DSC-Ressourcenmodule

Sehen Sie sich die Liste der einsatzbereiten Konfigurationsressourcen ("Posteingang") powerShell Desired State Configuration Resources an, die von Microsoft unterstützt werden, einschließlich:

  • -Umgebung: Verwaltung einer Umgebungsvariable für einen Rechner 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 -Funktion.
  • WindowsProcess: Starten oder Beenden eines Windows-Prozesses.

Sie finden auch PowerShell DSC-Ressourcenmodule im PowerShell-Katalog. Diese Galerie hostet Hunderte PowerShell-Module, die DSC-Ressourcen (Desired State Configuration) enthalten und von der Benutzer-Community eingereicht worden sind. Sie können Suchergebnisse filtern, indem Sie den Filter "DSC-Ressource" unter "Kategorien" anwenden. Dieses Repository ist nicht von Microsoft überprüft und enthält Ressourcen aus einer Vielzahl von Autoren und Herausgebern. PowerShell-Module sollten immer auf Sicherheit und Glaubwürdigkeit überprüft werden, da in beliebige Skripts beliebige Codes eingebunden werden können. Weitere Tipps zum Erstellen einer vertrauenswürdigen WinGet-Konfigurationsdatei finden Sie unter How to check the trustworthiness of a WinGet Configuration file .