Testreszabások sémareferenciája

A Microsoft Dev Box testreszabásai lehetővé teszik platformmérnökök és fejlesztők számára, hogy előtelepítsék az eszközöket, klónozzák a tárolókat, és konfigurálják a dev boxok beállításait YAML fájlok használatával. Ez a hivatkozás leírja a YAML fájlok jelenlegi sémáját és a beépített feladatokat, amelyeket a Dev Box testreszabások támogatnak.

Használja ezt a hivatkozást, amikor szükséges:

• Keresd meg az imagedefinition.yaml vagy task.yaml fájlban érvényes tulajdonságokat, típusokat és alapértelmezéseket.
• Erősítsd meg azokat a paramétereket, amelyeket a beépített ~/gitclone, ~/powershell, és ~/winget feladatok elfogadnak.
• Értsd meg, hogyan tasksműködnek együtt , userTasks, parameters, variables, és buildProperties amikor a Dev Box képet biztosít vagy testreszabásokat alkalmaz egy fejlesztő dobozra.

Testreszabási fájltípusok

A Dev Box testreszabások három YAML fájltípust használnak, mindegyiknek más célja és közönsége:

Beépített ~/gitclone, ~/powershell, és ~/winget feladatok bármely fejlesztőközpontból elérhetők katalógus hozzáadása nélkül. Ha egyedi feladatokat szeretnél hozzáadni ezeken a beépített megoldásokon kívül, definiáld őket egy task.yaml katalógusban lévő fájlokban, és név szerint hívd őket a képdefiníciód vagy a felhasználói testreszabási fájlodból. További információért lásd: a Microsoft Dev Box testreszabásai.

Imagedefinition.yaml-fájlok

Használd imagedefinition.yaml a kép, paraméterek, változók és testreszabási feladatok meghatározására, amelyeket a Dev Box alkalmaz képdefiníció létrehozásához.

Példa imagedefinition.yaml fájl

$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 tulajdonságok

$schema

(zsinór vagy szám)

Megadja a fájl séma verzióját. Jelenlegi példák használata 1.0.

$schema: "1.0"

name

(string, kötelező, 3-63 karakter)

Megadja a baráti nevet, amely képdefiníció kiválasztásakor jelenik meg. Ez a beállítás szabályozza a készletek létrehozásakor és frissítésekor elérhető képdefiníció nevét. A név nem tartalmazhat , , , , , <+;,=?>&_@*-|:]["/

name: example-image-definition

description

(húr)

Leírja a képmeghatározás célját.

description: Install core tools and clone the project repository.

image

(zsinór, kötelező)

Megadja az alapképet, amelyet a fejlesztő doboz képhez kell használni. A kép lehet piactéri kép vagy egy egyedi kép egy csatolt Azure Compute Galériából a formátumbangallery-name/image-name@version.

Examples:

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

image: my-gallery/my-image@0.0.1

Az Azure Compute Gallery csatolásához lásd: Configure Azure Compute Gallery for Microsoft Dev Box.

Ha szeretnéd megszerezni a fejlesztőközpontod által elérhető képek listáját, használd az Azure CLI-t:

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

Ha szükséges, először telepítsd a Dev Center Azure CLI kiterjesztést:

az extension add --name devcenter

parameters

(tárgy)

Névalapú bemeneti paramétereket definiál, amelyeket szintaxis segítségével tudsz a feladatokban {{parameterName}} hivatkozni.

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

Paraméterobjektum tulajdonságai

type

(string, kötelező, engedélyezett értékek: string, boolean, number)

Megadja a paraméteradattípust.

allowed

(zsinór tömbülése)

A paramétert egy rögzített engedélyezett stringértékek halmazára korlátozza.

default

(string, boolean vagy szám, kötelező)

A paraméter alapértelmezett értékét állítja be.

description

(húr)

Leírja a szerzők és eszközök paraméterét.

validationRegex

(húr)

Definiál egy reguláris kifejezést, amelynek a stringértékeknek egyezniük kell.

minLength

(egész szám)

A stringértékek minimális hosszát állítja be.

maxLength

(egész szám)

A string értékek maximális hosszát állítja be.

variables

(tárgy)

Meghatározza a névre keresztelt változókat, amelyeket újrahasználhatsz a képdefinícióban.

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

Változó objektum tulajdonságok

type

(string, kötelező, engedélyezett értékek: string, boolean, number)

Megadja a változó adattípust.

value

(string, boolean vagy szám, kötelező)

A változó értéket állítja be.

description

(húr)

Leírja a változót szerzők és eszközök számára.

tasks

(feladatobjektumok tömbje)

Testreszabási feladatokat listel, amelyek a rendszerkontextusban futnak a provisionálás során. A megadott konkrét bemeneti értékek feladatonként változnak. Minden feladatbejegyzésnek tartalmaznia name kell, és definiálhatja displayName, , descriptionparameters, és 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

A timeout tulajdonság opcionális, és másodpercekben mérhető, amikor használod .imagedefinition.yaml

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

Feladatbejegyzési tulajdonságok

name

(zsinór, kötelező)

Azonosítja a feladatot, amit teljesíteni kell. Használja az ~/ előtagot beépített feladatokhoz, például ~/winget, ~/powershell, és ~/gitclone.

displayName

(húr)

Rövid megjelenítési szöveget biztosít UI felületekhez.

description

(húr)

Leírja, mit tesz a feladat a képmeghatározásban.

parameters

(tárgy)

Megadja a feladathoz továbbított bemeneti értékeket. A paraméternevek és értéktípusok a kiválasztott feladattól függenek.

A paraméterdefiníciók ugyanazt a sémát követik, mint a task.yaml paramétertulajdonságok esetében. Részletekért lásd type, allowed, default, description, maxLengthvalidationRegexminLengthés .required

timeout

(egész szám)

Másodpercek alatt felülírja a feladat végrehajtásának időkorlátját.

userTasks

(feladatobjektumok tömbje)

A testreszabási feladatokat listázza a bejelentkezés után a felhasználói kontextusban futtatni. userTasks ugyanazt a feladatbejegyzési sémát használja, mint tasks.

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

buildProperties

(tárgy)

Definiálja az építés-specifikus beállításokat, amelyek testreszabják a képkészítési folyamatot.

buildProperties:
  networkConnection: corp-westus3

Build properties object properties

networkConnection

(húr)

Megadja a képkészítés során használt hálózati kapcsolatot. Használd ezt a beállítást, amikor a build-feladatoknak hozzáférést igényelnek olyan erőforrásokhoz, mint például privát tárolók vagy tárolófiókok, amelyek csak egy adott hálózati kapcsolaton keresztül érhetők el. A hálózati kapcsolatot a fejlesztőközponthoz kell csatlakoztatni, mielőtt képalkotásra használhatnád.

buildProperties:
  networkConnection: my-westus3

Beépített feladatok

Használj beépített feladatokat, amikor gyakori testreszabási műveletekre van szükséged, anélkül, hogy katalógust csatolnál. Használd az ~/ előtagot beépített feladat meghívására, például ~/winget, ~/powershell, vagy ~/gitclone.

• GitClone beépített feladat
• PowerShell beépített feladat
• WinGet beépített feladat

GitClone beépített feladat

Használd a GitClone beépített feladatát egy repository-t a fejlesztő dobozba.

Példa:

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

repositoryUrl

(zsinór, kötelező)

Megadja a klónozandó tár URL-jét.

directory

(string, alapértelmezett: C:\Workspaces)

Állítja be azt a könyvtárat, amely alatt a tároló klónozódik.

branch

(húr)

Kiválaszt egy ágat, amit klónozhat.

pat

(húr)

Személyes hozzáférési tokent biztosít hitelesített klón műveletekhez. Ha pat nincs megadva, a klónt sorba állítják az első felhasználó bejelentkezéséhez. Ha beadod pat, a feladat klónozhat a provisioning során. Használj Key Vault titkos hivatkozást a nyers titkos érték helyett.

A GitClone beépített feladata a PowerShell 7, Git és Git LFS telepítése közben is telepíti a végrehajtás során.

Beépített PowerShell-feladat

Használja a PowerShell beépített feladatot parancs vagy szkript futtatására.

Példa:

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

command

(húr)

Inline parancsot futtat. Ha megadod command, a script, scriptArgs, és scriptExecutionPolicy a paramétereket figyelmen kívül hagyjuk.

workingDirectory

(húr)

A parancs vagy szkript működési könyvtárát állítja be.

script

(húr)

Megadja a helyi vagy távoli PowerShell szkripthez vezető útvonalat, amit futtatni kell. Ezt a paramétert figyelmen kívül hagyjuk, ha command megadjuk.

scriptArgs

(húr)

Érvei a forgatókönyv mellett. Ezt a paramétert figyelmen kívül hagyjuk, ha command megadjuk.

scriptExecutionPolicy

(sor, alapértelmezett: Bypass)

A szkript végrehajtási szabályzatát állítja be. Ezt a paramétert figyelmen kívül hagyjuk, ha command megadjuk.

WinGet beépített feladat

Használd a WinGet beépített feladatot közvetlenül a csomag telepítéséhez, vagy alkalmazz egy WinGet konfigurációs fájlt.

Példa:

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

configurationFile

(húr)

A helyi gépen található WinGet konfigurációs YAML fájlra mutat.

downloadUrl

(húr)

Nyilvános URL-t ad meg egy WinGet konfigurációs YAML fájlhoz. A fájl letöltődik az útra .configurationFile

inlineConfigurationBase64

(húr)

Base64-en kódolt WinGet konfigurációs YAML fájlt biztosít. A feladat dekódolja az -re, configurationFilevagy ideiglenes fájlba, ha configurationFile nincs beállítva.

package

(húr)

Közvetlenül a név alapján telepít egy csomagot. Ha konfigurációs fájlforrást használsz, nem kell megadnod package.

version

(húr)

Egy adott csomagverziót telepít. Ha konfigurációs fájlforrást használsz, nem kell megadnod version.

task.yaml-fájlok

Használd task.yaml egy katalógusban újrahasználható testreszabási feladat meghatározására. A feladat definíciója leírja a feladat parancsát, metaadatait, paramétereit, dokumentációját és végrehajtási beállításait.

Amikor testreszabási feladatokat definiálsz, azonosítod azokat a feladatokat, amelyek a fejlesztők számára elérhetők a imagedefinition.yamldevbox.yaml fájlokban vagy a fájlokban. Feladatdefiníciókat használhatsz a magas jogosultságú műveletek korlátozására, például tetszőleges PowerShell parancsok futtatásának lehetőségére.

Példa task.yaml fájlra

$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

Az alábbi példa egy feladatdefiníciót mutat, amely egy PowerShell parancsot futtat egy adott munkakönyvtárban:

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

$schema

(zsinór, kötelező)

Megadja a feladatdefiníció séma verzióját. Jelenlegi példák használata 1.0.

name

(zsinór, kötelező)

Definiálja azt az azonosítót, amely a feladat vagy imagedefinition.yamldevbox.yaml fájlok hivatkozásához szolgál. A névnek egyedinek kell lennie annak a katalógusnak a kontextusában, amelyben a tevékenység létezik.

Ugyanazokat a névsori korlátozásokat használd, mint más Dev Box testreszabási artefakták. A névnek 3 és 63 karakter között kell lennie, alfanumerikus karakterrel kell kezdődnie, és csak alfanumerikus karaktereket tartalmaznia, -, ., vagy _. A / karakter fenntartva.

name: install-vsix-extension

command

(zsinór, kötelező)

Megadja a PowerShell parancsot, amely a feladatot megvalósítja. A parancs a helyi gépen fut Windows PowerShellben. Használj {{parameterName}} szintaxist a parancssorban lévő paraméterértékek hivatkozására.

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

Például:

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

description

(húr)

Leírja a feladat célját.

description: This task executes a PowerShell command.

author

(húr)

Azonosítja a feladatszerzőt az auditokhoz és hibaelhárításhoz.

author: Contoso Corporation

issueNotificationEmail

(húr)

E-mail címet biztosít, amivel a felhasználók megkereshetnek, ha problémáik vannak a feladattal. A termék funkcionalitása nem fogyasztja el ezt az értéket.

documentationURL

(húr)

Linkek a feladathoz tartozó dokumentációhoz.

documentationURL: https://link.to/documentation

licenseURL

(húr)

Linkek a feladat licenchez.

licenseURL: https://link.to/license

keywords

(zsinór tömbülése)

Felsorolja azokat a kulcsszavakat, amelyek segítenek a fogyasztóknak megtalálni a feladatot.

parameters

(tárgy)

Definiálja a feladat elnevezett bemeneti paramétereit. Minden gyermek elem egy paraméternevet képvisel, és meghatározhatja a paramétertípust, engedélyezett értékeket, alapértelmezett értéket, leírást, validációs szabályokat, hosszkorlátokat, valamint a paraméter szükségességét.

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

Paraméterdefiníciós tulajdonságok

type

(string, kötelező, engedélyezett értékek: string, boolean, number)

Megadja a bemeneti adattípust.

allowed

(zsinór tömbülése)

A bemenetet egy fix engedélyezett stringértékek halmazára korlátozza.

default

(string, boolean vagy szám)

A bemenet alapértelmezett értékét állítja be.

description

(húr)

Leírja a bemenetet.

validationRegex

(húr)

Definiál egy reguláris kifejezést, amelynek a stringértékeknek egyezniük kell.

minLength

(egész szám)

A stringértékek minimális hosszát állítja be.

maxLength

(egész szám)

A string értékek maximális hosszát állítja be.

required

(boolean)

Jelzi, hogy a bemenetet biztosítani kell-e. Ha nincs megadva, az alapértelmezett érték a következő false.

timeout

(egész szám, alapértelmezett: 30)

Az alapértelmezett feladatidőkorlátot percekben állítja be. Ha nem határozsz meg értéket, az alapértelmezett 30 perc.

timeout: 30

documentation

(tárgy)

Jegyzeteket és idézési példákat kínál, amelyeket a feladat fogyasztói használhatnak, amikor hozzáadják a feladatot egy képdefinícióhoz.

Dokumentációs objektum tulajdonságok

notes

(húr)

Útmutatást vagy figyelmeztetést ad a feladat fogyasztói számára.

examples

(feladatobjektumok tömbje)

Példákat mutat feladathívások úgy, hogy ugyanazt a sémát használják, mint a feladatbejegyzések .imagedefinition.yaml

rebootRequired

(boolean, alapértelmezett: hamis)

Jelzi, hogy a feladat végrehajtás után újraindítást igényel-e.

Kapcsolódó tartalom

• Csapat testreszabások konfigurálása – Hozz imagedefinition.yaml létre fájlokat, és alkalmazd őket egy fejlesztői doboz poolba.
• Konfigurálj egy felhasználói testreszabási fájlt a fejlesztő dobozodhoz – Írj és tölts fel egy személyes devbox.yaml fájlt.
• Feladatok konfigurálása Dev Box testreszabásokhoz – Készítsd task.yaml meg a fájlokat, és töld közzé őket egy katalóguson keresztül.
• Csatlakozás Azure-erőforrásokhoz vagy privát adattárak klónozása