Udostępnij przez

Jak utworzyć plik konfiguracji WinGet

Aby utworzyć plik konfiguracji WinGet:

  1. Utwórz plik YAML zgodnie z konwencją nazewnictwa plików Konfiguracji WinGet.
  2. Zapoznaj się z formatem pliku konfiguracji WinGet i połącz bieżący schemat pliku .
  3. Określ listę asercji (wymagane warunki wstępne) i Zasoby (lista wymaganych instalacji i konfiguracji ustawień w celu uzyskania środowiska deweloperskiego maszyny do żądanego stanu) do uwzględnienia w pliku.
  4. Zidentyfikuj moduły programu PowerShell i zasoby konfiguracji żądanego stanu (DSC) potrzebne do wykonania żądanych zadań konfiguracyjnych.
  5. Określ dyrektywy i ustawienia wymagane dla każdego zasobu konfiguracji.
  6. Określ zależności dla każdego zasobu.

Dowiedz się więcej o korzystaniu z polecenia WinGet configure.

Format pliku

Menedżer pakietów systemu Windows używa manifestów (plików YAML) do lokalizowania i instalowania pakietów dla użytkowników systemu Windows. Pliki konfiguracji WinGet używają tego samego formatu stylu YAML, dodając specyfikację schematu JSON, aby ułatwić zdefiniowanie struktury i walidacji pliku. Aby dodatkowo pomóc w wykrywaniu, czy format pliku konfiguracji WinGet jest prawidłowy, zalecamy użycie programu Visual Studio Code z rozszerzeniem YAML firmy RedHat w celu obsługi odpowiedniej składni, pomocy w wykrywaniu błędów formatowania, zapewnienia obsługi tzw. hover i automatycznego uzupełniania (po połączeniu z plikiem schematu JSON) oraz zapewnienia prawidłowego formatowania.

Konwencja nazewnictwa plików

Konwencja nazewnictwa pliku konfiguracji WinGet używa rozszerzenia pliku ".winget" (na przykład configuration.winget). W przypadku projektów opartych na usłudze Git domyślna konfiguracja powinna być przechowywana w katalogu ".config" pod adresem: ./config/configuration.winget. W niektórych przypadkach może być odpowiedni więcej niż jeden plik konfiguracji, biorąc pod uwagę różne łańcuchy narzędzi lub preferencje użytkownika. Te dodatkowe pliki konfiguracji powinny również znajdować się w katalogu ".config".

Sekcje pliku konfiguracji WinGet

Plik konfiguracji WinGet jest oddzielony dwoma podstawowymi sekcjami:

  1. Asercji: warunki wstępne wymagane do uruchomienia konfiguracji.
  2. Zasoby: lista oprogramowania i narzędzi do zainstalowania, ustawienia konfiguracji dla tych instalacji oraz ustawienia konfiguracji systemu operacyjnego Windows.

Sekcja Asercji

Lista twierdzeń obejmuje warunki wstępne wymagane dla zasobów wymienionych w tym pliku konfiguracji WinGet, aby mogły one działać pomyślnie na komputerze, na którym plik jest uruchamiany. Asercji można wykonać równolegle i nie wymagają żadnej kolejności sekwencyjnej.

Przykładowa aseracja:

  • Wersja systemu operacyjnego: Minimalna wersja systemu operacyjnego* zainstalowana na maszynie. Ponieważ funkcje są dodawane wraz z upływem czasu do systemu operacyjnego, niektóre są przywracane do obsługi wcześniejszych wersji, a niektóre nie są. Zawsze warto sprawdzić minimalną wersję systemu operacyjnego, aby określić, czy określone narzędzie lub funkcja, które są wymagane do konfiguracji, mogą być obsługiwane. Na przykład WinGet (Menedżer pakietów systemu Windows) wymaga co najmniej systemu Windows 10 w wersji 1809 lub nowszej. Wszystkie starsze wersje systemu Windows nie obsługują winGet. * Istnieje możliwość zmiany stanu systemu przez zasoby DSC programu PowerShell, ale nie byłoby odpowiednie wywołanie usługi Windows Update i zmodyfikowanie wersji systemu operacyjnego w konfiguracji projektu dla projektu typu open source.

Jeśli asercja zwraca wartość "false", aby wskazać, że system nie znajduje się w żądanym stanie, każdy zasoby identyfikujące tę asercję jako zależność przy użyciu pola dependsOn zostaną pominięte i nie zostaną uruchomione. W takim przypadku, mimo że żadne zmiany konfiguracji nie zostały zastosowane do środowiska systemu Windows, ta konfiguracja zostanie uznana za pomyślny wynik.

Sekcja Zasobów

Lista Zasobów obejmuje wszystkie oprogramowanie, narzędzia, pakiety itp., które należy zainstalować, oraz ustawienia konfiguracji dla systemu operacyjnego Windows lub zainstalowanych aplikacji. Każdy zasób musi mieć nazwę, opis dyrektywy, która ma zostać przeprowadzona, oraz moduł programu PowerShell, który będzie odpowiedzialny za przeprowadzenie tej dyrektywy, a także wszelkie skojarzone ustawienia lub zależności.

Przykładowy plik konfiguracji WinGet

Poniżej przedstawiono przykładowy plik sformatowany w konfiguracji 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

Składniki tego pliku składają się z:

  1. Schemat: pierwszy wiersz w pliku konfiguracji powinien zawierać następujący komentarz: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #> w celu określenia schematu DSC, do którego odnosi się plik. Aby znaleźć najnowszą wersję schematu konfiguracji WinGet, przejdź do strony https://aka.ms/configuration-dsc-schema/. Najnowszy numer schematu w momencie tego przykładu to 0.2, więc schemat został wprowadzony jako: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2.

  2. Właściwości: węzeł główny dla pliku konfiguracyjnego properties musi zawierać wersję konfiguracji (configurationVersion: 0.2.0 w tym przykładzie). Ta wersja powinna zostać zaktualizowana zgodnie z aktualizacjami pliku konfiguracji. Węzeł właściwości powinien zawierać assertions węzeł i resources węzeł.

  3. Stwierdzenia: podaj listę warunków wstępnych (lub przedwarunków) wymaganych do tej konfiguracji w tej sekcji.

  4. Zasoby: sekcje assertions listy i resources składają się z poszczególnych resource węzłów do reprezentowania skonfigurowanego zadania. Element resource powinien mieć nazwę modułu programu PowerShell, po którym następuje nazwa zasobu DSC modułu, który zostanie wywołany w celu zastosowania żądanego stanu: {ModuleName}/{DscResource}. Każdy zasób musi zawierać directives i settings. Opcjonalnie może również zawierać id wartość. Podczas stosowania konfiguracji narzędzie WinGet będzie wiedzieć, jak zainstalować moduł z galerii programu PowerShell i wywołać określony zasób DSC .

  5. Dyrektywy: Sekcja directives zawiera informacje o module i zasobie. Ta sekcja powinna zawierać wartość description do opisania zadania konfiguracyjnego wykonywanego przez moduł. Wartość allowPrerelease umożliwia wybranie, czy konfiguracja będzie mogła (true) używać modułów przedpremierowych z galerii programu PowerShell. Niektóre zasoby DSC mogą wymagać uruchomienia z uprawnieniami administratora. Pole securityContext: elevated w sekcji z dyrektywami zasobu jasno wskazuje to wymaganie. Po ustawieniu wartości elevated WinGet wyświetli monit o jednorazowe zatwierdzenie kontroli konta użytkownika na początku konfiguracji. Następnie usługa WinGet uruchomi dwa procesy: jeden, który uruchamia zasoby z podwyższonym poziomem uprawnień, a drugi z uprawnieniami bieżącego użytkownika.

  6. Ustawienia: wartość settings zasobu reprezentuje kolekcję par name-value przekazywanych do zasobu DSC programu PowerShell. Ustawienia mogą reprezentować dowolne elementy, od tego, czy tryb dewelopera jest włączony, do stosowania klucza reg, czy do ustanawiania określonego ustawienia sieci.

  7. Zależności: Wartość dependsOn zasobu określa, czy przed rozpoczęciem tego zadania należy ukończyć jakiekolwiek inne twierdzenia lub zasoby. Jeśli zależność nie powiedzie się, ten zasób również automatycznie zakończy się niepowodzeniem.

  8. identyfikator: unikatowy identyfikator określonego wystąpienia zasobu. Wartość id można użyć, jeśli inny zasób wymaga, aby ten zasób został zastosowany jako pierwszy.

Organizowanie sekcji Zasoby

Istnieje wiele podejść do rozważenia podczas określania sposobu organizowania sekcji Zasoby w pliku konfiguracji WinGet. Listę plików można organizować, wykonując następujące czynności:

  • Kolejność wykonywania: organizowanie listy zasobów zgodnie z kolejnością logiczną, w której powinny być wykonywane. Takie podejście może pomóc użytkownikowi zrozumieć i postępować zgodnie z krokami automatyzacji wykonywanymi po uruchomieniu pliku — co jest instalowane jako pierwsze, drugie, jakie ustawienie jest aktualizowane trzeci itd.
  • Możliwość niepowodzenia: Organizowanie listy zasobów zgodnie z prawdopodobieństwem potencjalnej awarii może pomóc użytkownikom wychwytywać problemy na wczesnym etapie procesu konfiguracji i pomóc im zrozumieć, dlaczego pozostałe kroki mogą zakończyć się niepowodzeniem, umożliwiając im identyfikowanie i wprowadzanie niezbędnych zmian przed zainwestowaniem dużej ilości czasu.
  • Grupowanie podobnych typów zasobów: Organizowanie listy zasobów przez grupowanie podobnych typów zasobów jest typowym podejściem w metodologiach inżynierii oprogramowania i może być najbardziej znane Tobie lub innym deweloperom korzystającym z pliku konfiguracji.

Zalecamy dołączenie pliku README.md z dowolnym opublikowanym plikiem konfiguracji WinGet typu open source zawierającym podejście organizacyjne struktury plików.

Używanie zmiennej ${WinGetConfigRoot}

Niektóre zasoby DSC mogą przyjmować parametr określający ścieżkę pliku. Zamiast określać pełną ścieżkę, możesz użyć zmiennej ${WinGetConfigRoot} do zdefiniowania katalogu roboczego, w którym winget configure jest wykonywane polecenie, i dołączyć ścieżkę względną, aby wskazać ten plik. Jest to przydatne w przypadku uogólniania pliku konfiguracji, aby był niezależny od komputera. Zasób Microsoft.VisualStudio.DSC/VSComponents w powyższym przykładzie przedstawia tę funkcję, używając ${WinGetConfigRoot} do wskazania pliku .vsconfig w katalogu głównym projektu. Oznacza to również, że użytkownik powinien upewnić się, że plik docelowy istnieje w ścieżce względnej względem bieżącego katalogu roboczego przed wykonaniem polecenia winget configure.

Gdzie znaleźć moduły zasobów DSC programu PowerShell

Zapoznaj się z listą gotowych do użycia ("skrzynka odbiorcza") zasobów konfiguracji żądanego stanu programu PowerShell obsługiwanych przez firmę Microsoft, w tym:

  • środowisko: Zarządzaj zmienną środowiskową dla maszyny lub procesu.
  • MsiPackage: zainstaluj lub odinstaluj pakiet MSI.
  • Rejestr: Zarządzaj kluczem lub wartością rejestru.
  • Skrypt: uruchom bloki skryptów programu PowerShell.
  • Usługa: Zarządzanie usługą systemu Windows.
  • WindowsFeature: instalowanie lub odinstalowywanie roli lub funkcji systemu Windows.
  • WindowsProcess: uruchamianie lub zatrzymywanie procesu systemu Windows.

Moduły zasobów DSC programu PowerShell można również znaleźć w galerii PowerShell . Ta galeria hostuje setki modułów programu PowerShell zawierających zasoby usługi Desired State Configuration (DSC) przesłane przez społeczność użytkowników. Wyniki wyszukiwania można filtrować, stosując filtr "Zasób DSC" w obszarze "Kategorie". To repozytorium nie jest zweryfikowane przez firmę Microsoft i zawiera zasoby różnych autorów i wydawców. Moduły programu PowerShell należy zawsze przeglądać pod kątem bezpieczeństwa i wiarygodności przed wykorzystaniem, ponieważ mogą zawierać dowolne skrypty. Zobacz Jak sprawdzić wiarygodność pliku konfiguracji WinGet w celu uzyskania więcej wskazówek dotyczących tworzenia wiarygodnego pliku konfiguracji WinGet.

  • Last updated on