Создание файла конфигурации WinGet

  • Статья

Чтобы создать файл конфигурации WinGet, выполните приведенные действия.

  1. Создайте ФАЙЛ YAML после соглашения об именовании файлов WinGet.
  2. Ознакомьтесь с форматом файла конфигурации WinGet и свяжите текущую схему файлов.
  3. Определите список утверждений (необходимые предварительные условия) и ресурсы (список необходимых установок и конфигураций конфигураций для получения среды разработки компьютера в нужном состоянии) для включения в файл.
  4. Определите модули PowerShell и ресурсы требуемой конфигурации состояния (DSC), необходимые для выполнения требуемых задач конфигурации.
  5. Определите директивы и параметры, необходимые для каждого ресурса конфигурации.
  6. Определите зависимости для каждого ресурса.

Дополнительные сведения об использовании команды настройки WinGet.

File format

Диспетчер пакетов Windows использует манифесты (ФАЙЛЫ YAML) для поиска и установки пакетов для пользователей Windows. Файлы конфигурации WinGet используют тот же формат стиля YAML, добавив спецификацию схемы JSON для определения структуры и проверки файла. Чтобы получить дополнительные сведения о том, является ли формат файла конфигурации WinGet допустимым, рекомендуется использовать Visual Studio Code с расширением YAML RedHat для поддержки правильного синтаксиса, помочь определить ошибки форматирования, обеспечить поддержку наведения указателя мыши и автозавершение (при связывании с файлом схемы JSON) и обеспечить допустимое форматирование.

Соглашение об именовании файлов

Соглашение об именовании файла конфигурации WinGet — это configuration.dsc.yamlсоглашение. Для проектов на основе Git конфигурация по умолчанию должна храниться в каталоге configurations по адресу: ./configurations/configuration.dsc.yaml

Разделы файла конфигурации WinGet

Файл конфигурации WinGet разделен на два основных раздела:

  1. Утверждения: предварительные условия, необходимые для запуска конфигурации.
  2. Ресурсы: список установленных программ и средств, параметров конфигурации для этих установок и параметров конфигурации операционной системы Windows.

Раздел "Утверждения"

Список утверждений охватывает предварительные условия (или предварительные требования), необходимые для ресурсов, перечисленных в этом файле конфигурации WinGet, для успешного выполнения на компьютере, на котором выполняется файл. Утверждения могут выполняться параллельно и не требуют последовательного порядка.

Пример утверждения:

  • Версия ОС: минимальная версия операционной системы*, установленная на компьютере. Поскольку функции добавляются со временем в ОС, некоторые из них поддерживают более ранние версии и некоторые из них не поддерживаются. Всегда полезно проверка для минимальной версии ОС, чтобы определить, может ли поддерживаться определенное средство или компонент, необходимые для настройки. Например, Для WinGet (Диспетчер пакетов Windows) требуется как минимум Windows 10 версии 1809 или более поздней. Все старые версии Windows не поддерживают WinGet. *Ресурсы PowerShell DSC можно изменить состояние системы, но не было бы целесообразно вызывать Обновл. Windows и изменять версию ОС в конфигурации проекта с открытым исходным кодом.

Если утверждение возвращает значение false, указывающее, что система не находится в требуемом состоянии, любой ресурс , определяющий это утверждение как зависимость, используя dependsOn поле, будет пропущен и не выполнен. В этом случае, несмотря на отсутствие изменений конфигурации в среде Windows, эта конфигурация будет считаться успешным результатом.

Раздел resources

Список ресурсов охватывает все программы, инструменты, пакеты и т. д., которые необходимо установить и параметры конфигурации для операционной системы Windows или установленных приложений. Каждому ресурсу потребуется указать имя, описание директивы и модуль PowerShell, который будет отвечать за выполнение этой директивы, а также любые связанные параметры или зависимости.

Пример файла конфигурации WinGet

Ниже приведен пример форматированного файла конфигурации configuration.dsc.yaml 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.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

Компоненты этого файла состоят из следующих компонентов:

  1. Схема: первая строка в файле конфигурации должна содержать следующий комментарий: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #> чтобы установить схему DSC, за которой следует файл. Чтобы найти последнюю версию схемы конфигурации WinGet, перейдите в раздел https://aka.ms/configuration-dsc-schema/. Последний номер схемы во время этого примера имеет значение0.2, поэтому схема была введена следующим образом: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2

  2. Свойства: корневой узел для файла конфигурации, properties который должен содержать версию конфигурации (configurationVersion: 0.2.0 в этом примере). Эта версия должна быть обновлена в соответствии с обновлениями файла конфигурации. Узел свойств должен содержать assertions узел и resources узел.

  3. Утверждения. Список предварительных условий (или предварительных требований), необходимых для этой конфигурации в этом разделе.

  4. Ресурсы: разделы assertionsresources списка состоят из отдельных resource узлов, которые представляют задачу настройки. Необходимо resource указать имя модуля PowerShell, за которым следует имя ресурса DSC модуля, который будет вызываться для применения требуемого состояния: {ModuleName}/{DscResource} Каждый ресурс должен включать directives и settings. При необходимости он также может включать id значение. При применении конфигурации WinGet будет знать, чтобы установить модуль из коллекция PowerShell и вызвать указанный ресурс DSC.

  5. Директивы. В directives разделе содержатся сведения о модуле и ресурсе. Этот раздел должен содержать description значение, описывающее задачу конфигурации, выполняемую модулем. Значение allowPrerelease позволяет выбрать, будет ли конфигурация разрешена (true) использовать модули Prerelease из коллекция PowerShell.

  6. Параметры. settings Значение ресурса представляет коллекцию пар "имя-значение", передаваемых в ресурс PowerShell DSC. Параметры может представлять все, включено ли режим разработчика, применение reg-ключа или установка определенного сетевого параметра.

  7. Зависимости: dependsOn значение ресурса определяет, следует ли завершить любое другое утверждение или ресурс до начала этой задачи. Если зависимость завершилась ошибкой, этот ресурс также автоматически завершится ошибкой.

  8. Идентификатор: уникальный идентификатор для конкретного экземпляра ресурса. Значение id можно использовать, если другой ресурс имеет зависимость от этого ресурса, применяемого первым.

Организация раздела "Ресурсы"

Существует несколько подходов, которые следует учитывать при определении способа упорядочивания раздела "Ресурсы" файла конфигурации WinGet. Список файлов можно упорядочить следующими способами:

  • Порядок выполнения: упорядочение списка ресурсов в соответствии с логическим порядком, в котором они должны выполняться. Этот подход может помочь пользователю понять и следовать инструкциям по автоматизации, выполняемым после запуска файла— то, что установлено первым, второе, что обновляется третьим, и т. д.
  • Возможность сбоя: организация списка ресурсов в соответствии с вероятностью потенциального сбоя может помочь пользователям поймать проблемы на ранних этапах процесса конфигурации и помочь им понять, почему оставшиеся шаги могут завершиться ошибкой, что позволяет им выявлять и вносить необходимые изменения до много времени.
  • Группирование аналогичных типов ресурсов: организация списка ресурсов путем группировки аналогичных типов ресурсов — это распространенный подход в методологиях разработки программного обеспечения и может быть наиболее знакомым для вас или другим разработчикам, использующим файл конфигурации.

Рекомендуется включить файл README.md с любым опубликованным файлом конфигурации WinGet с открытым исходным кодом, который включает в себя организационный подход к структуре файлов.

Использование переменной ${WinGetConfigRoot}

Некоторые ресурсы DSC могут приниматься в параметре, который задает путь к файлу. Вместо указания полного пути можно использовать переменную ${WinGetConfigRoot} , чтобы определить рабочий каталог, в котором winget configure выполняется команда , и добавить относительный путь, чтобы указать этот файл. Это полезно для обобщения файла конфигурации таким образом, чтобы он был не зависящим от компьютера. Ресурс Microsoft.VisualStudio.DSC/VSComponents в приведенном выше примере демонстрирует эту функцию, используя ${WinGetConfigRoot} файл VSCONFIG в корневом каталоге проекта. Это также означает, что пользователь должен убедиться, что целевой файл существует по относительному пути на основе текущего рабочего каталога перед выполнением winget configure команды.

Где найти модули ресурсов PowerShell DSC

Ознакомьтесь со списком готовых к использованию ("входящие") ресурсов конфигурации требуемого состояния PowerShell, поддерживаемых корпорацией Майкрософт, в том числе:

  • Среда: управление переменной среды для компьютера или процесса.
  • MsiPackage: установка или удаление пакета MSI.
  • Реестр. Управление разделом реестра или значением.
  • Скрипт. Запуск блоков скриптов PowerShell.
  • Служба: управление службой Windows.
  • WindowsFeature: установка или удаление роли или компонента Windows.
  • WindowsProcess: запуск или остановка процесса Windows.

В коллекция PowerShell также можно найти модули ресурсов PowerShell DSC. Эта коллекция содержит сотни модулей PowerShell, содержащих ресурсы требуемой конфигурации состояния (DSC), отправленные сообществом пользователей. Результаты поиска можно фильтровать, применяя фильтр "Ресурс DSC" в разделе "Категории". Этот репозиторий не проверяется корпорацией Майкрософт и содержит ресурсы из различных авторов и издателей. Модули PowerShell всегда должны проверяться на безопасность и доверие, прежде чем использовать любой произвольный скрипт. Узнайте, как проверка надежность файла конфигурации WinGet, чтобы получить дополнительные советы по созданию надежного файла конфигурации WinGet.