Sdílet prostřednictvím

Vytvoření konfiguračního souboru WinGet

Vytvoření konfiguračního souboru WinGet:

  1. Vytvořte soubor YAML podle zásad vytváření názvů konfiguračních souborů WinGet.
  2. Seznamte se s formátem konfiguračního souboru WinGet a propojte aktuální schéma souborů.
  3. Určete seznam výroků (požadované předpoklady) a Zdroje (seznam požadovaných instalací a konfigurací pro nastavení vývojového prostředí počítače do požadovaného stavu), které se mají zahrnout do souboru.
  4. Identifikujte moduly PowerShellu a prostředky DSC (Desired State Configuration) potřebné k provedení požadovaných úloh konfigurace.
  5. Určete direktivy a nastavení potřebná pro každý prostředek konfigurace.
  6. Určete závislosti pro každý prostředek.

Přečtěte si další informace o použití příkazu WinGet configure.

Formát souboru

Správce balíčků systému Windows používá manifesty (soubory YAML) k vyhledání a instalaci balíčků pro uživatele Windows. Konfigurační soubory WinGet používají stejný formát stylu YAML a přidávají specifikaci schématu JSON, která pomáhá definovat strukturu a ověření souboru. Pokud chcete dále pomoct při zjišťování, jestli je formát konfiguračního souboru WinGet platný, doporučujeme použít Visual Studio Code s příponou YAML od RedHat, která podporuje správnou syntaxi, pomáhá zjišťovat případné chyby formátování, poskytovat podporu přechodu myší a automatické dokončování (při propojení se souborem schématu JSON) a zajistit platné formátování.

Zásady vytváření názvů souborů

Konvence pro pojmenování konfiguračního souboru WinGet používá příponu souboru .winget (například configuration.winget). Pro projekty založené na Gitu by měla být výchozí konfigurace uložena v adresáři ".config" v: ./config/configuration.winget. V některých případech může být pro různé sady nástrojů nebo uživatelské předvolby vhodné více konfiguračních souborů. Tyto další konfigurační soubory by se také měly nacházet v adresáři ".config".

Oddíly konfiguračního souboru WinGet

Konfigurační soubor WinGet je rozdělený do dvou primárních částí:

  1. Asserce: Předpoklady potřebné ke spuštění konfigurace.
  2. Zdroje: Seznam softwaru a nástrojů, které se mají nainstalovat, nastavení konfigurace pro tyto instalace a nastavení konfigurací pro operační systém Windows.

Oddíl Prohlášení

Seznam tvrzení zahrnuje podmínky nezbytné pro úspěšné fungování prostředků uvedených v tomto konfiguračním souboru WinGet na počítači, kde je soubor spuštěn. Aserce mohou být prováděny paralelně a nevyžadují žádné konkrétní pořadí.

Příklad tvrzení

  • Verze operačního systému: Minimální verze operačního systému* nainstalovaná na počítači. Vzhledem k tomu, že se do operačního systému přidávají funkce v průběhu času, některé se zase přeportují tak, aby podporovaly dřívější verze a některé ne. Vždy je užitečné zkontrolovat minimální verzi operačního systému, abyste zjistili, jestli je pro konfiguraci podporovaný konkrétní nástroj nebo funkce. Například WinGet (Správce balíčků systému Windows) vyžaduje minimálně Windows 10 verze 1809 nebo novější. Žádné starší verze Windows nepodporují WinGet. * Prostředky DSC PowerShellu můžou změnit stav systému, ale není vhodné volat službu Windows Update a upravit verzi operačního systému v konfiguraci projektu pro opensourcový projekt.

Pokud kontrolní výraz vrátí hodnotu „false“, což označuje, že systém není v požadovaném stavu, jakýkoli prostředek , který identifikoval tento kontrolní výraz jako závislost pomocí pole dependsOn, bude přeskočen a nepodaří se jej spustit. V tomto případě by se i v případě, že v prostředí Windows nebyly použity žádné změny konfigurace, považuje se tato konfigurace za úspěšný výsledek.

Oddíl Zdroje informací

Seznam prostředků zahrnuje veškerý software, nástroje, balíčky atd., které je potřeba nainstalovat, a nastavení konfigurace pro operační systém Windows nebo nainstalované aplikace. Každý prostředek bude muset mít název, popis direktivy, která se má provést, a modul PowerShellu, který bude zodpovědný za provedení této směrnice, a také všechna přidružená nastavení nebo závislosti.

Příklad konfiguračního souboru WinGet

Následuje příklad souboru s formátováním konfigurace configuration.winget 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

Součásti tohoto souboru se skládají z:

  1. Schéma: První řádek v konfiguračním souboru by měl obsahovat následující komentář: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #> pro vytvoření schématu DSC následovaného souborem. Nejnovější verzi schématu konfigurace WinGet najdete v části https://aka.ms/configuration-dsc-schema/. Nejnovější číslo schématu v době tohoto příkladu je 0.2, takže schéma bylo zadáno jako: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2.

  2. Vlastnosti: Kořenový uzel konfiguračního souboru musí properties obsahovat verzi konfigurace (configurationVersion: 0.2.0 v tomto příkladu). Tato verze by se měla aktualizovat v souladu s aktualizacemi konfiguračního souboru. Uzel vlastností by měl obsahovat assertions uzel a resources uzel.

  3. Tvrzení: Uveďte předpoklady požadované pro tuto konfiguraci v této sekci.

  4. Zdroje: Sekce seznamu assertions a resources se skládají z jednotlivých resource uzlů, které představují úkol nastavení. Měl by být resource označen názvem modulu PowerShell, po kterém následuje název prostředku DSC tohoto modulu, který bude vyvolán pro uplatnění požadovaného stavu: {ModuleName}/{DscResource}. Každý prostředek musí obsahovat directives a settings. Volitelně může také obsahovat id hodnotu. Při použití konfigurace WinGet pozná, že má nainstalovat modul z PowerShell galerie a vyvolá zadaný prostředek DSC .

  5. Směrnice: Část directives poskytuje informace o modulu a prostředku. Tato část by měla obsahovat description hodnotu, která popisuje úlohu konfigurace, kterou modul provádí. Hodnota allowPrerelease umožňuje zvolit, zda bude konfiguraci povoleno (true) používat moduly předběžné verze z Galerie PowerShell. Některé prostředky DSC můžou být potřeba spustit s oprávněními správce. Pole securityContext: elevated v oddílu direktiv zdroje označuje tento požadavek. Při nastavení elevated WinGet na začátku konfigurace vyzve k jednomu schválení UAC. WinGet pak spustí dva procesy: jeden, který spouští prostředky se zvýšenými oprávněními, a druhý, který spouští prostředky s oprávněními aktuálního uživatele.

  6. Nastavení: Hodnota settings prostředku představuje kolekci párů název-hodnota, které se předávají prostředku DSC PowerShellu. Nastavení může představovat cokoli z toho, jestli je povolený vývojářský režim, použití klíče reg nebo vytvoření konkrétního nastavení sítě.

  7. Závislosti: Hodnota dependsOn zdroje určuje, zda musí být před zahájením tohoto úkolu dokončen nějaký jiný výrok nebo zdroj. Pokud závislost selhala, tento prostředek také automaticky selže.

  8. ID: Jedinečný identifikátor pro konkrétní instanci zdroje. Hodnotu id lze použít, pokud jiný prostředek má nejprve závislost na tomto prostředku.

Uspořádání sekce Zdroje

Při určování způsobu uspořádání oddílu Prostředky konfiguračního souboru WinGet je potřeba vzít v úvahu několik přístupů. Seznam souborů můžete uspořádat podle:

  • Pořadí provádění: Uspořádání seznamu prostředků podle logického pořadí, ve kterém se mají provést. Tento přístup může uživateli pomoct pochopit a postupovat podle kroků automatizace provedených po spuštění souboru – co je nainstalováno jako první, druhé, jaké nastavení se aktualizuje za třetí atd.
  • Možnost selhání: Uspořádání seznamu prostředků podle pravděpodobnosti potenciálního selhání může uživatelům pomoct zachytit problémy včas v procesu konfigurace a pomoct jim pochopit, proč zbývající kroky nemusí selhat, což jim umožní identifikovat a provést potřebné změny dříve, než je mnoho času investováno.
  • Seskupení podobných typů prostředků: Uspořádání seznamu prostředků seskupením podobných typů prostředků je běžný přístup v metodologiích softwarového inženýrství a může být pro vás nebo pro ostatní vývojáře, kteří využívají váš konfigurační soubor, běžný přístup.

Doporučujeme přidat soubor README.md s libovolným open source publikovaným konfiguračním souborem WinGet, který zahrnuje organizační přístup struktury souborů.

Použití proměnné ${WinGetConfigRoot}

Některé prostředky DSC mohou převzít parametr, který určuje cestu k souboru. Místo zadání úplné cesty můžete pomocí proměnné ${WinGetConfigRoot} definovat pracovní adresář, ve kterém winget configure se příkaz spouští, a připojit relativní cestu, která má odkazovat na tento soubor. To je užitečné pro generalizaci konfiguračního souboru tak, aby byl nezávislý na počítači. Zdroj Microsoft.VisualStudio.DSC/VSComponents v příkladu výše ukazuje tuto funkci tím, že využívá ${WinGetConfigRoot} k odkazování na soubor .vsconfig v kořenovém adresáři projektu. To také znamená, že uživatel by měl před spuštěním winget configure příkazu zajistit, aby cílový soubor existoval na relativní cestě na základě současného pracovního adresáře.

Kde lze najít moduly zdrojů PowerShell DSC

Podívejte se na seznam připravených k okamžitému použití („inbox“) prostředků konfigurace požadovaného stavu pro PowerShell, které podporuje společnost Microsoft, včetně:

  • prostředí: Správa proměnné prostředí pro počítač nebo proces
  • MsiPackage: Nainstalujte nebo odinstalujte balíček MSI.
  • registru: Správa klíče nebo hodnoty registru
  • Skript: Spusťte bloky skriptů PowerShellu.
  • Služba: Správa služby systému Windows.
  • WindowsFeature: Nainstalujte nebo odinstalujte roli nebo funkci Systému Windows.
  • WindowsProcess: Spusťte nebo zastavte proces Systému Windows.

Moduly prostředků DSC PowerShellu najdete také v PowerShell galerii. Tato galerie hostuje stovky modulů PowerShellu obsahujících prostředky DSC (Desired State Configuration) odeslané komunitou uživatelů. Výsledky hledání můžete filtrovat použitím filtru "Prostředek DSC" v části Kategorie. Toto úložiště microsoft neověřuje a obsahuje prostředky od různých autorů a vydavatelů. Moduly PowerShellu by se měly před používáním libovolných skriptů vždy kontrolovat z hlediska zabezpečení a důvěryhodnosti. Další tipy k vytvoření důvěryhodného konfiguračního souboru WinGet najdete v tématu Jak zkontrolovat důvěryhodnost konfiguračního souboru WinGet .

  • Last updated on