Schemareferens för anpassningar

Microsoft Dev Box-anpassningar låter plattformsingenjörer och utvecklare förinstallera verktyg, klona repositorier och konfigurera inställningar på utvecklingsboxar genom att använda YAML-filer. Denna referens beskriver det aktuella schemat för YAML-filerna och de inbyggda uppgifterna som Dev Box-anpassningar stödjer.

Använd denna referens när du behöver:

• Kolla upp egenskaper, typer och standardinställningar som är giltiga i en imagedefinition.yaml eller task.yaml-fil .
• Bekräfta de parametrar som de inbyggda ~/gitclone, ~/powershell, och ~/winget tasks accepterar.
• Förstå hur tasks, userTasks, parameters, , variables, och buildProperties samarbeta när Dev Box tillhandahåller en image eller tillämpar anpassningar på en dev box.

Anpassningsfiltyper

Dev Box-anpassningar använder tre YAML-filtyper, var och en med olika syfte och målgrupp:

Inbyggda ~/gitclone, ~/powershell, och ~/winget uppgifter finns tillgängliga från vilket utvecklingscenter som helst utan att behöva bifoga en katalog. För att lägga till egna uppgifter utöver dessa inbyggda funktioner, definiera dem i task.yaml filer i en katalog och anropa dem med namn från din bilddefinition eller användaranpassningsfil. För mer information, se Microsoft Dev Box-anpassningar.

Imagedefinition.yaml-filer

imagedefinition.yaml Använd för att definiera bilder, parametrar, variabler och anpassningsuppgifter som Dev Box använder när den skapar en bilddefinition.

Exempel på imagedefinition.yaml-fil

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

$schema

(sträng eller nummer)

Specificerar schemaversionen för filen. Nuvarande exempel använder 1.0.

$schema: "1.0"

name

(sträng, krävs, 3–63 tecken)

Specificerar det vänliga namnet som visas när du väljer en bilddefinition. Den här inställningen styr namnet på den bilddefinition som är tillgänglig när du skapar och uppdaterar pooler. Namnet kan inte innehålla /, ", [, ], :, |, >+=*,;@?&<, eller börja med _ eller .-

name: example-image-definition

description

(sträng)

Beskriver syftet med bilddefinitionen.

description: Install core tools and clone the project repository.

image

(snöre, krävs)

Specificerar basavbilden som ska användas för dev box-avbilden. Avbilden kan vara en marknadsplatsbild eller en anpassad bild från ett bifogat Azure Compute-galleri i formatet gallery-name/image-name@version.

Examples:

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

image: my-gallery/my-image@0.0.1

För att bifoga ett Azure Compute Gallery, se Configure Azure Compute Gallery for Microsoft Dev Box.

För att få en lista över bilder som ditt utvecklingscenter kan komma åt, använd Azure CLI:

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

Om det behövs, installera Dev Center Azure CLI-tillägget först:

az extension add --name devcenter

parameters

(objekt)

Definierar namngivna indataparametrar som du kan referera till i uppgifter genom att använda {{parameterName}} syntax.

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

Parameterobjektets egenskaper

type

(sträng, obligatoriskt, tillåtna värden: sträng, booleskt, tal)

Specificerar parameterdatatypen.

allowed

(strängarray)

Begränsar parametern till en fast uppsättning tillåtna strängvärden.

default

(sträng, booleskt eller nummer, krävs)

Sätter standardvärdet för parametern.

description

(sträng)

Beskriver parametern för författare och verktyg.

validationRegex

(sträng)

Definierar ett reguljärt uttryck som strängvärden måste matcha.

minLength

(heltal)

Sätter minsta längd för strängvärden.

maxLength

(heltal)

Sätter maximal längd för strängvärden.

variables

(objekt)

Definierar namngivna variabler som du kan återanvända i bilddefinitionen.

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

Egenskaper för variabla objekt

type

(sträng, obligatoriskt, tillåtna värden: sträng, booleskt, tal)

Specificerar variabeldatatypen.

value

(sträng, booleskt eller nummer, krävs)

Sätter variabelvärdet.

description

(sträng)

Beskriver variabeln för författare och verktyg.

tasks

(array av uppgiftsobjekt)

Listar anpassningsuppgifter som ska köras i systemkontext under provisionering. De specifika indatavärden du anger varierar mellan uppgifter. Varje uppgiftspost måste inkludera name och kan även definiera displayName, description, , parametersoch 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

Egenskapen timeout är valfri och mäts i sekunder när du använder den i imagedefinition.yaml.

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

Egenskaper för uppgiftsinmatning

name

(snöre, krävs)

Identifierar uppgiften som ska utföras. Använd prefixet ~/ för inbyggda uppgifter, såsom ~/winget, ~/powershell, och ~/gitclone.

displayName

(sträng)

Tillhandahåller kort visningstext för UI-ytor.

description

(sträng)

Beskriver vad uppgiften gör i bilddefinitionen.

parameters

(objekt)

Definierar de indatavärden som skickas till uppgiften. Parameternamn och värdetyper beror på den valda uppgiften.

Parameterdefinitionerna följer samma schema som beskrivs för task.yaml parameteregenskaper. För detaljer, se , , , , , validationRegex, minLength, maxLengthoch required. descriptiondefaultallowedtype

timeout

(heltal)

Åsidosätter timeout för uppgiftsutförandet på några sekunder.

userTasks

(array av uppgiftsobjekt)

Listar anpassningsuppgifter som körs i användarkontext efter inloggning. userTasks använder samma uppgiftsinmatningsschema som tasks.

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

buildProperties

(objekt)

Definierar byggspecifika inställningar som anpassar bildbyggarprocessen.

buildProperties:
  networkConnection: corp-westus3

Byggegenskaper objektegenskaper

networkConnection

(sträng)

Specificerar nätverksanslutningen som används vid bildskapandet. Använd denna inställning när bygguppgifter behöver tillgång till resurser som privata arkiv eller lagringskonton som endast är tillgängliga via en specifik nätverksanslutning. Nätverksanslutningen måste vara ansluten till utvecklingscentret innan du kan använda den för bildskapande.

buildProperties:
  networkConnection: my-westus3

Inbyggda uppgifter

Använd inbyggda uppgifter när du behöver vanliga anpassningsåtgärder utan att bifoga en katalog. Använd prefixet ~/ för att anropa en inbyggd uppgift, till exempel ~/winget, ~/powershell, eller ~/gitclone.

• GitClone inbyggd uppgift
• PowerShell inbyggd uppgift
• WinGet inbyggd uppgift

GitClone inbyggd uppgift

Använd GitClones inbyggda uppgift för att klona ett repository in i utvecklingsmaskinen.

Exempel:

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

repositoryUrl

(snöre, krävs)

Specificerar att arkivets URL ska klonas.

directory

(sträng, standard: C:\Workspaces)

Anger katalogen under vilken arkivet klonas.

branch

(sträng)

Väljer en gren att klona.

pat

(sträng)

Tillhandahåller en personlig åtkomsttoken för autentiserade klonoperationer. När pat den inte tillhandahålls ställs klonen i kö för den första användarens inloggning. När du tillhandahåller pat, kan uppgiften klona under provisioneringen. Använd en Key Vault-hemlighetsreferens istället för ett rått hemlighetsvärde.

Den inbyggda GitClone-uppgiften installerar också PowerShell 7, Git och Git LFS under körning.

Inbyggd PowerShell-uppgift

Använd PowerShell-funktionen för att köra ett kommando eller skript.

Exempel:

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

command

(sträng)

Kör ett inline-kommando. Om du anger command, ignoreras script, scriptArgs, och scriptExecutionPolicy parametrarna.

workingDirectory

(sträng)

Sätter arbetskatalogen för kommandot eller skriptet.

script

(sträng)

Specificerar vägen till ett lokalt eller fjärrstyrt PowerShell-skript som ska köras. Denna parameter ignoreras när command den tillhandahålls.

scriptArgs

(sträng)

Ger argument för manuset. Denna parameter ignoreras när command den tillhandahålls.

scriptExecutionPolicy

(sträng, standard: Bypass)

Sätter exekveringspolicyn för skriptet. Denna parameter ignoreras när command den tillhandahålls.

WinGet-inbyggd uppgift

Använd WinGet-inbyggd uppgift för att installera ett paket direkt eller applicera en WinGet-konfigurationsfil.

Exempel:

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

configurationFile

(sträng)

Pekar på en WinGet-konfigurations-YAML-fil på den lokala maskinen.

downloadUrl

(sträng)

Specificerar en publik URL för en WinGet-konfigurations-YAML-fil. Filen laddas ner till sökvägen i configurationFile.

inlineConfigurationBase64

(sträng)

Tillhandahåller en Base64-kodad WinGet-konfigurations-YAML-fil. Uppgiften avkodar den till configurationFile, eller till en temporär fil om configurationFile det inte är satt.

package

(sträng)

Installerar ett paket direkt efter namn. Om du använder en konfigurationsfilkälla behöver du inte tillhandahålla package.

version

(sträng)

Installerar en specifik paketversion. Om du använder en konfigurationsfilkälla behöver du inte tillhandahålla version.

task.yaml-filer

Använd task.yaml för att definiera en återanvändbar anpassningsuppgift i en katalog. En uppgiftsdefinition beskriver kommandon, metadata, parametrar, dokumentation och exekveringsinställningar för uppgiften.

När du definierar anpassningsuppgifter identifierar du vilka uppgifter som är tillgängliga för utvecklare att använda i imagedefinition.yaml eller devbox.yaml filer. Du kan använda uppgiftsdefinitioner för att begränsa högprivilegierade åtgärder, såsom möjligheten att köra godtyckliga PowerShell-kommandon.

Exempel på task.yaml-fil

$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

Följande exempel visar en uppgiftsdefinition som kör ett PowerShell-kommando i en specifik arbetskatalog:

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

$schema

(snöre, krävs)

Specificerar schemaversionen för uppgiftsdefinitionen. Nuvarande exempel använder 1.0.

name

(snöre, krävs)

Definierar identifieraren som används för att referera till uppgiften från imagedefinition.yaml eller devbox.yaml filerna. Namnet måste vara unikt i kontexten för katalogen där uppgiften finns.

Använd samma namngivningsbegränsningar som andra artefakter för anpassning i Dev Box. Namnet måste vara mellan 3 och 63 tecken, börja med ett alfanumeriskt tecken och endast innehålla alfanumeriska tecken, -, ., eller _. Tecknet / är reserverat.

name: install-vsix-extension

command

(snöre, krävs)

Specificerar PowerShell-kommandot som implementerar uppgiften. Kommandot körs i Windows PowerShell på den lokala datorn. Använd {{parameterName}} syntax för att referera parametervärden i kommandosträngen.

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

Ett exempel:

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

description

(sträng)

Beskriver syftet med uppgiften.

description: This task executes a PowerShell command.

author

(sträng)

Identifierar uppgiftsförfattaren för revisioner och felsökning.

author: Contoso Corporation

issueNotificationEmail

(sträng)

Tillhandahåller en e-postadress som användare kan kontakta om de har problem med uppgiften. Produktfunktionalitet konsumerar inte detta värde.

documentationURL

(sträng)

Länkar till dokumentation för uppgiften.

documentationURL: https://link.to/documentation

licenseURL

(sträng)

Länkar till uppgiftslicensen.

licenseURL: https://link.to/license

keywords

(strängarray)

Listar nyckelord som hjälper konsumenter att hitta uppgiften.

parameters

(objekt)

Definierar namngivna indataparametrar för uppgiften. Varje barnobjekt representerar ett parameternamn och kan definiera parametertyp, tillåtna värden, standardvärde, beskrivning, valideringsregler, längdgränser och om parametern behövs.

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

Egenskaper för parameterdefinition

type

(sträng, obligatoriskt, tillåtna värden: sträng, booleskt, tal)

Specificerar indatatypen.

allowed

(strängarray)

Begränsar indata till en fast uppsättning tillåtna strängvärden.

default

(sträng, boolean eller tal)

Sätter standardvärdet för indatan.

description

(sträng)

Beskriver indatan.

validationRegex

(sträng)

Definierar ett reguljärt uttryck som strängvärden måste matcha.

minLength

(heltal)

Sätter minsta längd för strängvärden.

maxLength

(heltal)

Sätter maximal längd för strängvärden.

required

(booleskt)

Anger om indata måste tillhandahållas. Om det utelämnas är falsestandardvärdet .

timeout

(heltal, standard: 30)

Sätter standardtidsavslutningen för uppgiften på några minuter. Om du inte anger ett värde är standardvärdet 30 minuter.

timeout: 30

documentation

(objekt)

Tillhandahåller anteckningar och invocation-exempel som uppgiftskonsumenter kan använda när de lägger till uppgiften i en bilddefinition.

Dokumentationsobjektets egenskaper

notes

(sträng)

Lägger till vägledning eller förbehåll för användarna av uppgiften.

examples

(array av uppgiftsobjekt)

Visar exempel på uppgiftsinkallelser genom att använda samma schema som uppgiftsposter i imagedefinition.yaml.

rebootRequired

(boolean, standard: falsk)

Indikerar om uppgiften kräver omstart efter körning.

Relaterat innehåll

• Konfigurera teamanpassningar – Skapa imagedefinition.yaml filer och applicera dem på en dev box-pool.
• Konfigurera en användaranpassningsfil för din utvecklingslåda – skapa och ladda upp en personlig devbox.yaml fil.
• Konfigurera uppgifter för Dev Box-anpassningar – Skapa task.yaml filer och publicera dem via en katalog.
• Ansluta till Azure-resurser eller klona privata lagringsplatser