Referenční dokumentace schématu vlastního nastavení

Přizpůsobení Microsoft Dev Boxu umožňuje platformovým inženýrům a vývojářům předinstalovat nástroje, klonovat repozitáře a konfigurovat nastavení na vývojářských boxech pomocí YAML souborů. Tato reference popisuje aktuální schéma pro YAML soubory a vestavěné úkoly, které podporují přizpůsobení Dev Boxu.

Použijte tento zdroj, když potřebujete:

• Vyhledejte vlastnosti, typy a výchozí nastavení, které jsou platné v souboru imagedefinition.yaml nebo task.yaml .
• Potvrďte parametry, které vestavěné ~/gitclone~/powershell, , a úkoly přijímají~/winget.
• Pochopte, jak tasks, userTasks, parameters, variables, a spolupracují buildProperties , když Dev Box poskytuje obrázek nebo aplikuje úpravy na dev box.

Typy souborů pro přizpůsobení

Přizpůsobení Dev Boxu používají tři typy souborů YAML, z nichž každý má jiný účel a cílovou skupinu:

Vestavěné ~/gitclone, ~/powershell, a úkoly jsou ~/winget dostupné z jakéhokoli vývojového centra bez připojení katalogu. Chcete-li přidat vlastní úkoly nad rámec těchto vestavěných prvků, definujte je v task.yaml souborech v katalogu a volejte je podle názvu z definice obrázku nebo souboru pro uživatelskou úpravu. Pro více informací viz Microsoft Dev Box přizpůsobení.

Soubory Imagedefinition.yaml

Použijte imagedefinition.yaml k definování obrázků, parametrů, proměnných a úprav, které Dev Box používá při vytváření definice obrázku.

Příklad souboru 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

Vlastnosti imagedefinition.yaml

$schema

(řetězec nebo číslo)

Specifikuje verzi schématu souboru. Současné příklady používají 1.0.

$schema: "1.0"

name

(řetězec, povinný, 3-63 znaků)

Specifikuje název přátele, který se zobrazí při výběru definice obrázku. Toto nastavení řídí název definice obrázku, která je k dispozici při vytváření a aktualizaci fondů. Název nesmí obsahovat /, ", [, ], :, |, <, +>=*&?,@;, mezeru, ani začínat na _ nebo .-

name: example-image-definition

description

(struna)

Popisuje účel definice obrázku.

description: Install core tools and clone the project repository.

image

(provázek, vyžadován)

Specifikuje základní obrázek pro obrázek vývojové krabice. Obrázek může být obrázek z tržiště nebo vlastní obrázek z připojené Azure Compute Gallery ve formátu gallery-name/image-name@version.

Examples:

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

image: my-gallery/my-image@0.0.1

Pro připojení Azure Compute Gallery viz Configure Azure Compute Gallery for Microsoft Dev Box.

Pro získání seznamu obrázků, ke kterým má vaše vývojové centrum přístup, použijte Azure CLI:

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

Pokud je potřeba, nejprve nainstalujte rozšíření Dev Center Azure CLI:

az extension add --name devcenter

parameters

(objekt)

Definuje pojmenované vstupní parametry, na které se můžete odkazovat v úlohách pomocí {{parameterName}} syntaxe.

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

Vlastnosti parametru objektu

type

(řetězec, povinné, povolené hodnoty: řetězec, boolean, číslo)

Specifikuje typ dat parametru.

allowed

(pole provázků)

Omezuje parametr na pevnou množinu povolených hodnot řetězců.

default

(požadovaný řetězec, boolean nebo číslo)

Nastaví výchozí hodnotu parametru.

description

(struna)

Popisuje parametr autorů a nástrojů.

validationRegex

(struna)

Definuje regulární výraz, kterému musí hodnoty řetězců odpovídat.

minLength

(celé číslo)

Nastavuje minimální délku pro hodnoty řetězců.

maxLength

(celé číslo)

Nastavuje maximální délku pro hodnoty řetězců.

variables

(objekt)

Definuje pojmenované proměnné, které můžete znovu použít v definici obrázku.

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

Vlastnosti proměnných objektů

type

(řetězec, povinné, povolené hodnoty: řetězec, boolean, číslo)

Specifikuje datový typ proměnné.

value

(požadovaný řetězec, boolean nebo číslo)

Nastavuje hodnotu proměnné.

description

(struna)

Popisuje proměnnou pro autory a nástroje.

tasks

(pole objektů úloh)

Uvádí úkoly přizpůsobení, které se spustí v kontextu systému během provisioningu. Konkrétní vstupní hodnoty, které zadáte, se liší podle úkolu. Každý úkol musí obsahovat name a může také definovat displayName, description, parameters, a 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

Vlastnost timeout je volitelná a při použití v imagedefinition.yaml.

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

Vlastnosti zadávání úkolů

name

(provázek, vyžadován)

Identifikuje úkol, který má splnit. Použijte předponu ~/ pro vestavěné úkoly, jako ~/wingetjsou , ~/powershell, a ~/gitclone.

displayName

(struna)

Poskytuje krátký zobrazovací text pro UI povrchy.

description

(struna)

Popisuje to, co úkol dělá v definici obrázku.

parameters

(objekt)

Definuje vstupní hodnoty předávané úkolu. Názvy parametrů a typy hodnot závisí na zvoleném úkolu.

Definice parametrů se řídí stejným schématem popsaným pro task.yaml vlastnosti parametrů. Pro podrobnosti viz , , , , , validationRegex, minLength, , maxLength, a .requireddescriptiondefaultallowedtype

timeout

(celé číslo)

Přepíše časový limit provedení úkolu během několika sekund.

userTasks

(pole objektů úloh)

Uvádí úkoly přizpůsobení, které se spustí v uživatelském kontextu po přihlášení. userTasks používá stejné schéma zadávání úloh jako tasks.

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

buildProperties

(objekt)

Definuje nastavení specifická pro sestavu, která přizpůsobují proces sestavování obrázků.

buildProperties:
  networkConnection: corp-westus3

Vlastnosti objektu Vlastnosti buildu

networkConnection

(struna)

Specifikuje síťové připojení používané při vytváření obrazu. Toto nastavení použijte, když build úkoly potřebují přístup ke zdrojům, jako jsou soukromé repozitáře nebo úložné účty, které jsou dostupné pouze přes specifické síťové připojení. Síťové připojení musí být připojeno k vývojovému centru, než ho můžete použít pro tvorbu obrázků.

buildProperties:
  networkConnection: my-westus3

Předdefinované úkoly

Používejte vestavěné úkoly, když potřebujete běžné úpravy bez připojení katalogu. Použijte předponu ~/ k volání vestavěné úlohy, například ~/winget, ~/powershell, nebo ~/gitclone.

• Vestavěná úloha GitClone
• PowerShell vestavěná úloha
• Vestavěná úloha WinGet

Vestavěná úloha GitClone

Použijte vestavěnou úlohu GitClone k naklonování repozitáře do vývojářské krabice.

Příklad:

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

repositoryUrl

(provázek, vyžadován)

Specifikuje URL repozitáře pro klonování.

directory

(string, výchozí: C:\Workspaces)

Nastaví adresář, pod kterým je repozitář klonován.

branch

(struna)

Vybere větev ke klonování.

pat

(struna)

Poskytuje osobní přístupový token pro ověřené klonovací operace. Když pat není dodán, klon je zařazen do fronty pro první přihlášení uživatele. Když dodáš pat, úkol se může během provisioningu klonovat. Použijte odkaz na Key Vault secret místo surové hodnoty tajemství.

Vestavěná úloha GitClone také instaluje PowerShell 7, Git a Git LFS během spuštění.

Integrovaná úloha PowerShellu

Použijte vestavěnou úlohu PowerShell k spuštění příkazu nebo skriptu.

Příklad:

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

command

(struna)

Spustí příkaz přímo do řady. Pokud uvedete command, scriptscriptArgs, a parametry jsou scriptExecutionPolicy ignorovány.

workingDirectory

(struna)

Nastavuje pracovní adresář pro příkaz nebo skript.

script

(struna)

Specifikuje cestu k lokálnímu nebo vzdálenému PowerShell skriptu, který má spuštěn. Tento parametr je ignorován, pokud command je poskytnut.

scriptArgs

(struna)

Poskytuje argumenty pro scénář. Tento parametr je ignorován, pokud command je poskytnut.

scriptExecutionPolicy

(řetězec, výchozí: Bypass)

Nastavuje politiku provádění skriptu. Tento parametr je ignorován, pokud command je poskytnut.

Předdefinovaná úloha WinGet

Použijte vestavěnou úlohu WinGet k přímé instalaci balíčku nebo aplikaci konfiguračního souboru WinGet.

Příklad:

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

configurationFile

(struna)

Ukazuje na konfigurační YAML soubor WinGet na lokálním počítači.

downloadUrl

(struna)

Specifikuje veřejnou URL pro konfigurační YAML soubor WinGet. Soubor je stažen do cesty v configurationFile.

inlineConfigurationBase64

(struna)

Poskytuje YAML soubor pro konfiguraci WinGet kódovaný v Base64. Úkol ho dekóduje na configurationFile, nebo do dočasného souboru, pokud configurationFile není nastaven.

package

(struna)

Nainstaluje balíček přímo podle jména. Pokud použijete zdrojový kód konfiguračního souboru, nemusíte dodávat package.

version

(struna)

Nainstaluje konkrétní verzi balíčku. Pokud použijete zdrojový kód konfiguračního souboru, nemusíte dodávat version.

soubory task.yaml

Použijte task.yaml k definování znovupoužitelného úkolu přizpůsobení v katalogu. Definice úkolu popisuje příkazy, metadata, parametry, dokumentaci a nastavení provádění úkolu.

Když definujete úkoly přizpůsobení, identifikujete úkoly, které jsou vývojářům dostupné pro použití v imagedefinition.yaml souborech nebo devbox.yaml souborech. Definice úloh můžete použít k omezení akcí s vysokými oprávněními, například možnost spouštět libovolné PowerShell příkazy.

Příklad souboru 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

Následující příklad ukazuje definici úlohy, která spouští PowerShell příkaz v konkrétním pracovním adresáři:

$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.

Vlastnosti Task.yaml

$schema

(provázek, vyžadován)

Specifikuje verzi schématu pro definici úkolu. Současné příklady používají 1.0.

name

(provázek, vyžadován)

Definuje identifikátor použitý k odkazování na úkol ze imagedefinition.yaml souborů or devbox.yaml souborů. Název musí být jedinečný v kontextu katalogu, ve kterém úloha existuje.

Používejte stejná omezení pojmenování jako jiné artefakty přizpůsobení Dev Boxu. Název musí mít mezi 3 a 63 znaky, začínat alfanumerickým znakem a obsahovat pouze alfanumerické znaky, -, ., nebo _. Znak / je vyhrazen.

name: install-vsix-extension

command

(provázek, vyžadován)

Specifikuje PowerShell příkaz, který úkol implementuje. Příkaz běží ve Windows PowerShellu na lokálním počítači. Použijte {{parameterName}} syntaxi k odkazování na hodnoty parametrů v příkazovém řetězci.

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

Příklad:

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

description

(struna)

Popisuje účel úkolu.

description: This task executes a PowerShell command.

author

(struna)

Identifikuje autora úkolu pro audity a řešení problémů.

author: Contoso Corporation

issueNotificationEmail

(struna)

Poskytuje e-mailovou adresu, na kterou se uživatelé mohou obrátit, pokud mají s úkolem problémy. Funkčnost produktu tuto hodnotu nespotřebovává.

documentationURL

(struna)

Odkazy na dokumentaci k tomuto úkolu.

documentationURL: https://link.to/documentation

licenseURL

(struna)

Odkazy na licenci na úkol.

licenseURL: https://link.to/license

keywords

(pole provázků)

Uvádí klíčová slova, která pomáhají spotřebitelům najít daný úkol.

parameters

(objekt)

Definuje pojmenované vstupní parametry pro danou úlohu. Každý podřízený prvek představuje název parametru a může definovat typ parametru, povolené hodnoty, výchozí hodnotu, popis, validační pravidla, limity délky a zda je parametr vyžadován.

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

Vlastnosti definice parametrů

type

(řetězec, povinné, povolené hodnoty: řetězec, boolean, číslo)

Specifikuje typ vstupních dat.

allowed

(pole provázků)

Omezuje vstup na pevnou sadu povolených hodnot řetězců.

default

(struna, boolean nebo číslo)

Nastaví výchozí hodnotu pro vstup.

description

(struna)

Popisuje vstup.

validationRegex

(struna)

Definuje regulární výraz, kterému musí hodnoty řetězců odpovídat.

minLength

(celé číslo)

Nastavuje minimální délku pro hodnoty řetězců.

maxLength

(celé číslo)

Nastavuje maximální délku pro hodnoty řetězců.

required

(boolean)

Označuje, zda je nutné vstup dodat. Pokud tento parametr vynecháte, výchozí hodnota je false.

timeout

(celočíselné, výchozí: 30)

Nastaví výchozí časový limit úkolu na minuty. Pokud nezadáte hodnotu, výchozí je 30 minut.

timeout: 30

documentation

(objekt)

Poskytuje poznámky a příklady vyvolávání, které mohou uživatelé úkolu použít, když úkol přidají do definice obrázku.

Vlastnosti dokumentačního objektu

notes

(struna)

Přidává rady nebo upozornění pro uživatele tohoto úkolu.

examples

(pole objektů úloh)

Ukazuje příklady volání úloh použitím stejného schématu jako záznamy úloh v imagedefinition.yaml.

rebootRequired

(boolean, výchozí: nepravda)

Označuje, zda úkol vyžaduje restart po vykonání.

Související obsah

• Nastavte týmové přizpůsobení – Vytvářejte imagedefinition.yaml soubory a aplikujte je do dev box poolu.
• Nastavte si uživatelský soubor pro přizpůsobení pro váš vývojářský box – Vytvořte a nahrajte osobní devbox.yaml soubor.
• Konfigurujte úkoly pro přizpůsobení Dev Boxu – Vytvářejte task.yaml soubory a publikujte je prostřednictvím katalogu.
• Připojení k prostředkům Azure nebo klonování privátních úložišť