Справочник по схеме настроек

Настройки Microsoft Dev Box позволяют инженерам и разработчикам платформы предварительно устанавливать инструменты, клонировать репозитории и настраивать настройки на dev box с помощью YAML-файлов. Этот справочник описывает текущую схему для YAML-файлов и встроенных задач, которые поддерживают кастомизации Dev Box.

Используйте этот справочник, когда нужно:

• Посмотрите свойства, типы и параметры по умолчанию, которые действительны в файлах imagedefinition.yaml или task.yaml .
• Подтвердите параметры, которые принимают встроенные ~/gitcloneзадачи , ~/powershellи ~/winget задачи.
• Поймите, как tasks, userTasks, variablesparameters, и buildProperties работают вместе, когда Dev Box предоставляет образ или применяет настройки к devbox.

Типы файлов настройки

Кастомизации Dev Box используют три типа файлов YAML, каждый из которых имеет свою цель и аудиторию:

Встроенные ~/gitclone, ~/powershellи ~/winget задачи доступны в любом центре разработки без прикрепления каталога. Чтобы добавить пользовательские задачи помимо встроенных, определите их в task.yaml файлах каталога и называйте по имени из вашего файла определения изображения или пользовательской настройки. Для получения дополнительной информации смотрите настройки Microsoft Dev Box.

Файлы Imagedefinition.yaml

Используйте imagedefinition.yaml для определения изображения, параметров, переменных и задач настройки, которые DevBox применяет при создании определения изображения.

Пример файла imagedefinition.yaml

$schema: "1.0"
name: example-image-definition
description: Install core tools and clone the project repository.
image: microsoftvisualstudio_visualstudioplustools_vs-2022-ent-general-win11-m365-gen2
parameters:
  repositoryBranch:
    type: string
    default: main
    description: Branch to clone during setup.
variables:
  workspaceRoot:
    type: string
    value: C:\Workspaces
    description: Root directory for repositories.
tasks:
  - name: ~/winget
    parameters:
      package: Git.Git
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/example-org/example-repo.git
      directory: C:\Workspaces
      branch: "{{repositoryBranch}}"
userTasks:
  - name: ~/powershell
    parameters:
      command: code C:\Workspaces\example-repo
buildProperties:
  networkConnection: corp-westus3

Свойства imagedefinition.yaml

$schema

(строка или номер)

Указывает версию схемы для файла. Современные примеры используют 1.0.

$schema: "1.0"

name

(обязательная строка, 3-63 символа)

Задаёт удобное имя, которое отображается при выборе определения изображения. Этот параметр определяет имя определения образа, которое доступно при создании и обновлении пулов. Название не может содержать /, ", [, @<|>:+]?&,;*=пробелы или начинаться с .-_

name: example-image-definition

description

(струна)

Описывает цель определения изображения.

description: Install core tools and clone the project repository.

image

(верёвка, требуется)

Указывает базовый образ для изображения dev box. Изображение может быть изображением маркетплейса или пользовательским образом из приложенной вычислительной галереи Azure в формате gallery-name/image-name@version.

Examples:

image: microsoftwindowsdesktop_windows-ent-cpc_win11-21h2-ent-cpc-m365

image: my-gallery/my-image@0.0.1

Чтобы прикрепить Azure Compute Gallery, см. Configure Azure Compute Gallery for Microsoft Dev Box.

Чтобы получить список изображений, к которым ваш центр разработчиков может получить доступ, используйте Azure CLI:

az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"

При необходимости сначала установите расширение Dev Center Azure CLI:

az extension add --name devcenter

parameters

(объект)

Определяет именованные входные параметры, на которые можно обращаться в задачах с помощью {{parameterName}} синтаксиса.

parameters:
  repositoryBranch:
    type: string
    default: main
    description: Branch to clone during setup.

Свойства параметрического объекта

type

(строка, требуется, допустимые значения: строка, булева, число)

Задаёт тип данных параметров.

allowed

(массив строк)

Ограничивает параметр фиксированным набором разрешённых значений строк.

default

(требуется струна, булев или число)

Устанавливает значение параметра по умолчанию.

description

(струна)

Описывает параметр для авторов и инструменты.

validationRegex

(струна)

Определяет регулярное выражение, которому должны совпадать значения строк.

minLength

(целое число)

Устанавливает минимальную длину для значений строк.

maxLength

(целое число)

Устанавливает максимальную длину для значений строк.

variables

(объект)

Определяет именованные переменные, которые можно использовать повторно в определении изображения.

variables:
  workspaceRoot:
    type: string
    value: C:\Workspaces
    description: Root directory for repositories.

Свойства переменных объектов

type

(строка, требуется, допустимые значения: строка, булева, число)

Задаёт тип данных переменных.

value

(требуется струна, булев или число)

Устанавливает значение переменной.

description

(струна)

Описывает переменную для авторов и инструментов.

tasks

(массив объектов задач)

Перечисляет задачи настройки для выполнения в системном контексте во время предоставления. Конкретные значения входных данных, которые вы даёте, зависят от задачи. Каждая запись задачи должна включать name и также может определять displayName, description, parameters, и timeout.

tasks:
  - name: ~/winget
    parameters:
      package: Git.Git
  - name: ~/gitclone
    timeout: 1800
    parameters:
      repositoryUrl: https://github.com/example-org/example-repo.git
      directory: C:\Workspaces

Свойство timeout необязательно и измеряется секундами при использовании в imagedefinition.yaml.

tasks:
  - name: ~/powershell
    timeout: 1800
    parameters:
      command: <command>

Свойства ввода задачи

name

(верёвка, требуется)

Определяет задачу, которую нужно выполнить. Используйте ~/ префикс для встроенных задач, таких ~/wingetкак , ~/powershellи ~/gitclone.

displayName

(струна)

Предоставляет короткий текст для интерфейсных поверхностей.

description

(струна)

Описывает, что делает задача в определении изображения.

parameters

(объект)

Определяет входные значения, передаваемые задаче. Имена параметров и типы значений зависят от выбранной задачи.

Определения параметров следуют той же схеме, что и свойства task.yaml параметров. Для подробностей см. type, allowed, default, descriptionvalidationRegex, , minLengthmaxLength, , и required.

timeout

(целое число)

Переопределяет тайм-аут выполнения задачи за считанные секунды.

userTasks

(массив объектов задач)

Список задач настройки для выполнения в пользовательском контексте после входа. userTasks использует ту же схему ввода задачи, что и tasks.

userTasks:
  - name: ~/powershell
    parameters:
      command: code C:\Workspaces\example-repo

buildProperties

(объект)

Определяет настройки, специфичные для сборки, которые настраивают процесс создания изображений.

buildProperties:
  networkConnection: corp-westus3

Свойства объекта Свойства Build Properties

networkConnection

(струна)

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

buildProperties:
  networkConnection: my-westus3

Встроенные задачи

Используйте встроенные задачи, когда нужны обычные действия кастомизации без прикрепления каталога. Используйте ~/ префикс, чтобы вызвать встроенную задачу, например ~/winget, ~/powershellили ~/gitclone.

• Встроенная задача GitClone
• Встроенная задача PowerShell
• Встроенная задача WinGet

Встроенная задача GitClone

Используйте встроенную задачу GitClone, чтобы клонировать репозиторий в devbox.

Пример:

tasks:
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/microsoft/calculator
      directory: C:\Workspaces
      branch: main

repositoryUrl

(верёвка, требуется)

Указывает URL репозитория для клонирования.

directory

(строка, по умолчанию: C:\Workspaces)

Устанавливает каталог, в который клонируется репозиторий.

branch

(струна)

Выбирает ветку для клонирования.

pat

(струна)

Предоставляет личный токен доступа для аутентифицированных операций клонирования. Когда pat он не предоставлен, клон попадает в очередь для первого входа пользователя. Когда вы подаёте patпродукты, задача может клонироваться во время провизии. Используйте секретный справочник Key Vault вместо чистого секретного значения.

Встроенная задача GitClone также устанавливает PowerShell 7, Git и Git LFS во время выполнения.

Встроенная задача PowerShell

Используйте встроенную задачу PowerShell для запуска команды или скрипта.

Пример:

tasks:
  - name: ~/powershell
    parameters:
      command: Write-Host "Hello from Dev Box"

command

(струна)

Выполняет встроенную команду. Если вы предоставите command, scriptscriptArgs, , и scriptExecutionPolicy параметры игнорируются.

workingDirectory

(струна)

Устанавливает рабочую папку для команды или скрипта.

script

(струна)

Указывает путь к локальному или удалённому скрипту PowerShell для запуска. Этот параметр игнорируется при command предоставлении.

scriptArgs

(струна)

Приводит аргументы для сценария. Этот параметр игнорируется при command предоставлении.

scriptExecutionPolicy

(строка, по умолчанию: обход)

Устанавливает политику выполнения скрипта. Этот параметр игнорируется при command предоставлении.

Встроенная задача WinGet

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

Пример:

tasks:
  - name: ~/winget
    parameters:
      package: GitHub.GitHubDesktop
      version: 3.4.16

configurationFile

(струна)

Указывает на YAML-файл конфигурации WinGet на локальной машине.

downloadUrl

(струна)

Указывает публичный URL для YAML-файла конфигурации WinGet. Файл загружается в путь в configurationFile.

inlineConfigurationBase64

(струна)

Предоставляет YAML-файл конфигурации WinGet, закодированный в Base64. Задача декодирует его в configurationFile, или в временный файл, если configurationFile не установлен.

package

(струна)

Устанавливает пакет напрямую по названию. Если вы используете исходный код конфигурационного файла, не нужно предоставлять package.

version

(струна)

Устанавливает определённую версию пакета. Если вы используете исходный код конфигурационного файла, не нужно предоставлять version.

Файлы task.yaml

Используйте task.yaml для определения повторно используемой задачи настройки в каталоге. Определение задачи описывает команду, метаданные, параметры, документацию и настройки выполнения задачи.

Когда вы определяете задачи кастомизации, вы определяете, какие задачи доступны разработчикам для использования в imagedefinition.yaml файлах или devbox.yaml файлах. Вы можете использовать определения задач для ограничения действий с высокими привилегиями, например, возможность запускать произвольные команды PowerShell.

Пример файла task.yaml

$schema: "1.0"
name: install-vsix-extension
description: Install a Visual Studio extension from a VSIX package.
author: Contoso Corporation
command: .\install-extension.ps1 -VsixPath {{vsixPath}}
documentationURL: https://contoso.example/devbox/install-vsix-extension
keywords:
  - visual-studio
  - extension
parameters:
  vsixPath:
    type: string
    required: true
    description: Path to the VSIX package.
timeout: 30
rebootRequired: false
documentation:
  notes: Use a path that is available during task execution.
  examples:
    - name: install-vsix-extension
      parameters:
        vsixPath: .\extensions\contoso.vsix

Следующий пример показывает определение задачи, которое запускает команду PowerShell в конкретной рабочей директории:

$schema: "1.0"
name: powershell
description: Execute a PowerShell command.
author: Microsoft Corporation
command: .\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}
parameters:
  command:
    type: string
    default: ""
    required: true
    description: The command to execute.
  workingDirectory:
    type: string
    default: ""
    required: false
    description: The working directory in which to execute the command.

Свойства task.yaml

$schema

(верёвка, требуется)

Указывает версию схемы для определения задачи. Современные примеры используют 1.0.

name

(верёвка, требуется)

Определяет идентификатор, используемый для ссылки на задачу из imagedefinition.yaml или devbox.yaml файлов. Имя должно быть уникальным в контексте каталога, в котором существует задача.

Используйте те же ограничения по названию, что и другие артефакты кастомизации Dev Box. Название должно состоять от 3 до 63 символов, начинаться с буквенно-цифрового символа и содержать только буквенно-цифровые символы, -, ., или _. Символ / зарезервирован.

name: install-vsix-extension

command

(верёвка, требуется)

Указывает команду PowerShell, реализующую задачу. Команда выполняется в Windows PowerShell на локальном компьютере. Используйте {{parameterName}} синтаксис для ссылки на значения параметров в командной строке.

command: .\install-extension.ps1 -VsixPath {{vsixPath}}

Рассмотрим пример.

command: .\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}

description

(струна)

Описывает цель задачи.

description: This task executes a PowerShell command.

author

(струна)

Определяет автора задачи для аудита и устранения неполадок.

author: Contoso Corporation

issueNotificationEmail

(струна)

Предоставляет адрес электронной почты, к которому пользователи могут обратиться при возникновении проблем с задачей. Функциональность продукта не потребляет эту ценность.

documentationURL

(струна)

Ссылки на документацию по заданию.

documentationURL: https://link.to/documentation

licenseURL

(струна)

Ссылки на лицензию задачи.

licenseURL: https://link.to/license

keywords

(массив строк)

Перечисляет ключевые слова, которые помогают потребителям найти задание.

parameters

(объект)

Определяет именованные входные параметры задачи. Каждый дочерний элемент представляет имя параметра и может определять тип параметра, разрешённые значения, значение по умолчанию, описание, правила валидации, ограничения по длине и необходимость параметра.

parameters:
  vsixPath:
    type: string
    required: true
    description: Path to the VSIX package.

Свойства определения параметров

type

(строка, требуется, допустимые значения: строка, булева, число)

Указывает тип входных данных.

allowed

(массив строк)

Ограничивает вход фиксированным набором разрешённых значений строк.

default

(струна, булев или число)

Устанавливает значение по умолчанию для входа.

description

(струна)

Описывает входные данные.

validationRegex

(струна)

Определяет регулярное выражение, которому должны совпадать значения строк.

minLength

(целое число)

Устанавливает минимальную длину для значений строк.

maxLength

(целое число)

Устанавливает максимальную длину для значений строк.

required

(булевый)

Указывает, необходимо ли предоставить вход. Если опущено, значение по умолчанию равно false.

timeout

(целое число, по умолчанию: 30)

Устанавливает тайм-аут задачи по умолчанию за минуты. Если не указать значение, по умолчанию — 30 минут.

timeout: 30

documentation

(объект)

Предоставляет заметки и примеры вызовов, которые пользователи задач могут использовать при добавлении задачи в определение изображения.

Свойства объекта документации

notes

(струна)

Добавляет рекомендации или оговорки для пользователей задачи.

examples

(массив объектов задач)

Показывает примеры вызовов задач, используя ту же схему, что и записи задач в imagedefinition.yaml.

rebootRequired

(булевый, по умолчанию: ложный)

Указывает, требует ли задача перезагрузки после выполнения.

Связанный контент

• Настраивайте настройки команды — создавайте imagedefinition.yaml файлы и применяйте их в пуле dev box.
• Настройте файл настройки пользователя для вашего devbox — Автор и загрузка личного devbox.yaml файла.
• Настраивайте задачи для кастомизации Dev Box — авторизуйте task.yaml файлы и публикуйте их через каталог.
• Подключение к ресурсам Azure или клонирование частных репозиториев