Поделиться через

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

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

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

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

Формат файла

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

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

Соглашение о наименовании файла конфигурации WinGet заключается в использовании расширения .winget (например configuration.winget). Для проектов на основе Git конфигурация по умолчанию должна храниться в каталоге.configпо адресу: ./config/configuration.winget В некоторых случаях несколько файлов конфигурации могут быть подходящими с учетом различных цепочки инструментов или пользовательских настроек. Эти дополнительные файлы конфигурации также должны находиться в каталоге ".config".

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

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

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

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

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

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

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

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

Раздел "Ресурсы"

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

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

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

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

  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 . Некоторые ресурсы DSC при необходимости могут выполняться с правами администратора. Поле securityContext: elevated в разделе директив ресурса указывает на это требование. Если задано значение elevated, WinGet будет запрашивать одно утверждение UAC в начале конфигурации. Затем WinGet запустит два процесса: один из них выполняет ресурсы с повышенными привилегиями, а другой — с правами текущего пользователя.

  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 DSC в PowerShell Gallery. Эта коллекция содержит сотни модулей PowerShell, содержащих ресурсы требуемой конфигурации состояния (DSC), отправленные сообществом пользователей. Результаты поиска можно фильтровать, применяя фильтр "Ресурс DSC" в разделе "Категории". Этот репозиторий не проверен корпорацией Майкрософт и содержит ресурсы из различных авторов и издателей. Модули PowerShell всегда должны проверяться на безопасность и надежность перед использованием, так как в них может быть включен произвольный скрипт. См. «Как проверить надежность файла конфигурации WinGet» для получения дополнительных советов по созданию надежного файла конфигурации WinGet.