Informazioni di riferimento sullo schema delle personalizzazioni

Le personalizzazioni di Microsoft Dev Box permettono agli ingegneri e agli sviluppatori di preinstallare strumenti, clonare repository e configurare le impostazioni sulle dev box utilizzando file YAML. Questo riferimento descrive lo schema attuale per i file YAML e i compiti integrati supportati dalle personalizzazioni di Dev Box.

Usa questo riferimento quando hai bisogno:

  • Cerca le proprietà, i tipi e i valori predefiniti validi in un file imagedefinition.yaml o task.yaml .
  • Conferma i parametri che i task integrati ~/gitcloneaccettano~/powershell~/winget.
  • Capire come tasks, userTasks, parameters, variables, e buildProperties funzionano insieme quando Dev Box fornisce un'immagine o applica personalizzazioni a una devbox.

Tipi di file di personalizzazione

Le personalizzazioni di Dev Box utilizzano tre tipi di file YAML, ciascuno con uno scopo e un pubblico diversi:

File Purpose Autore Posizione in cui viene eseguita
imagedefinition.yaml Definisce un'immagine riutilizzabile per un pool di sviluppatori. Elenca l'immagine base, i parametri, le variabili, i compiti di sistema, i compiti utente e le proprietà di build da applicare quando Dev Box crea una definizione di immagine. Platform engineer o team lead Conservati in un catalogo allegato a un progetto; applicato a ogni dev box creato da un pool che fa riferimento alla definizione dell'immagine.
task.yaml Definisce un compito di personalizzazione riutilizzabile e parametrizzato che viene aggiunto a un catalogo. Permette agli amministratori di avvolgere la logica PowerShell con metadati, validazione dei parametri, documentazione e impostazioni di esecuzione. Tecnico di piattaforma Memorizzata in un catalogo annesso a un centro sviluppo; chiamato per nome da imagedefinition.yaml file di OR devbox.yaml .
devbox.yaml File di personalizzazione utente personale caricato durante la creazione della dev box. Si applica solo alla scatola di sviluppo a cui è collegato. Sviluppatore individuale Caricato dal disco locale o consultato da un repository nel portale sviluppatori.

Le attività integrate ~/gitclone, ~/powershell, e ~/winget sono disponibili da qualsiasi centro sviluppo senza allegare un catalogo. Per aggiungere compiti personalizzati oltre a quelli integrati, definili in task.yaml file in un catalogo e chiamali per nome dal file di definizione immagine o personalizzazione utente. Per maggiori informazioni, consulta le personalizzazioni di Microsoft Dev Box.

File Imagedefinition.yaml

Usa imagedefinition.yaml per definire l'immagine, i parametri, le variabili e i compiti di personalizzazione che Dev Box applica quando crea una definizione di immagine.

Esempio di file 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

Proprietà di Imagedefinition.yaml

Proprietà Richiesto Digitare Description
$schema stringa o numero Specifica la versione dello schema per il file.
name ✅ Stringa Definisce il nome amichevole per la definizione dell'immagine.
description Stringa Descrive la definizione dell'immagine.
image ✅ Stringa Identifica l'immagine base da usare per l'immagine della dev box.
Parametri object Definisce parametri di input a cui i compiti possono fare riferimento nella definizione dell'immagine.
variables object Definisce valori riutilizzabili per la definizione dell'immagine.
Compiti Array degli oggetti task Elenca le attività di personalizzazione del contesto di sistema da eseguire durante il provisioning.
userTask Array degli oggetti task Elenca le attività di personalizzazione del contesto utente da eseguire dopo l'accesso.
buildProprietà object Definisce impostazioni specifiche per la creazione dell'immagine.

$schema

(stringa o numero)

Specifica la versione dello schema per il file. Gli esempi attuali usano 1.0.

$schema: "1.0"

name

(stringa, obbligatoria, 3-63 caratteri)

Specifica il nome amichevole mostrato quando selezioni una definizione di un'immagine. Questa impostazione controlla il nome della definizione dell'immagine disponibile quando si creano e aggiornano i pool. Il nome non può contenere /, ", [, ], >|+<=:, *&?,@;spazio bianco, né iniziare con _ o .-

name: example-image-definition

description

(corda)

Descrive lo scopo della definizione dell'immagine.

description: Install core tools and clone the project repository.

image

(corda, necessaria)

Specifica l'immagine base da usare per l'immagine dev box. L'immagine può essere un'immagine marketplace o un'immagine personalizzata da una galleria di calcolo Azure allegata nel formato gallery-name/image-name@version.

Esempi:

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

image: my-gallery/my-image@0.0.1

Per allegare una galleria di calcolo Azure, vedi Configura la galleria di calcolo Azure per Microsoft Dev Box.

Per ottenere un elenco di immagini a cui il tuo centro di sviluppo può accedere, usa interfaccia della riga di comando di Azure:

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

Se necessario, installa prima l'estensione Dev Center interfaccia della riga di comando di Azure:

az extension add --name devcenter

parameters

(oggetto)

Definisce parametri di input nominati a cui puoi fare riferimento nei task usando {{parameterName}} la sintassi.

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

Proprietà degli oggetti parametri

Proprietà Richiesto Digitare Description
tipo ✅ Stringa Specifica il tipo di dato del parametro.
consentito matrice di stringhe Restringe il parametro a una lista fissa di valori di stringhe.
default ✅ stringa, booleana o numero Imposta il valore predefinito per il parametro.
description Stringa Descrive il parametro.
validazioneRegex Stringa Valida i valori della stringa rispetto a un'espressione regolare.
minLength Intero Imposta la lunghezza minima per i valori della stringa.
maxLength Intero Imposta la lunghezza massima per i valori della stringa.

type

(stringa, obbligatoria, valori consentiti: stringa, booleana, numero)

Specifica il tipo di dato del parametro.

allowed

(schiera di corde)

Restringe il parametro a un insieme fisso di valori consentiti di stringhe.

default

(stringa, booleana o numero, necessaria)

Imposta il valore predefinito per il parametro.

description

(corda)

Descrive il parametro per autori e strumenti.

validationRegex

(corda)

Definisce un'espressione regolare che i valori della stringa devono corrispondere.

minLength

(intero)

Imposta la lunghezza minima per i valori della stringa.

maxLength

(intero)

Imposta la lunghezza massima per i valori della stringa.

variables

(oggetto)

Definisce variabili nominate che puoi riutilizzare nella definizione dell'immagine.

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

Proprietà variabile dell'oggetto

Proprietà Richiesto Digitare Description
tipo ✅ Stringa Specifica il tipo di dato variabile.
valore ✅ stringa, booleana o numero Imposta il valore variabile.
description Stringa Descrive la variabile.

type

(stringa, obbligatoria, valori consentiti: stringa, booleana, numero)

Specifica il tipo di dato variabile.

value

(stringa, booleana o numero, necessaria)

Imposta il valore variabile.

description

(corda)

Descrive la variabile per autori e strumenti.

tasks

(array di oggetti di attività)

Elenca i compiti di personalizzazione da eseguire nel contesto di sistema durante il provisioning. I valori specifici di input che fornisci variano a seconda del compito. Ogni voce di compito deve includere name e può anche definire displayName, description, parameters, e 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

La timeout proprietà è opzionale e si misura in secondi quando la usi in imagedefinition.yaml.

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

Proprietà di inserimento del compito

Proprietà Richiesto Digitare Description
name ✅ Stringa Identifica il compito da invocare.
displayName Stringa Fornisce un breve testo dell'interfaccia utente per il compito.
description Stringa Descrive cosa fa il compito.
Parametri object Fornisce i valori di input per il compito.
timeout Intero Sovrascrive il tempo di esecuzione del compito in pochi secondi.

name

(corda, necessaria)

Identifica il compito da eseguire. Usa il ~/ prefisso per compiti integrati, come ~/winget, ~/powershell, e ~/gitclone.

displayName

(corda)

Fornisce un breve testo di visualizzazione per le superfici dell'interfaccia utente.

description

(corda)

Descrive cosa fa il compito nella definizione dell'immagine.

parameters

(oggetto)

Definisce i valori di input passati al compito. I nomi dei parametri e i tipi di valore dipendono dal compito selezionato.

Le definizioni dei parametri seguono lo stesso schema descritto per le task.yaml proprietà dei parametri. Per dettagli, vedi type, allowed, default, description, validationRegex, minLength, , maxLengthe required.

timeout

(intero)

Sovrascrive il timeout di esecuzione del compito in pochi secondi.

userTasks

(array di oggetti di attività)

Elenca le attività di personalizzazione da eseguire nel contesto utente dopo l'accesso. userTasks usa lo stesso schema di inserimento del compito di tasks.

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

buildProperties

(oggetto)

Definisce impostazioni specifiche per la build che personalizzano il processo di creazione dell'immagine.

buildProperties:
  networkConnection: corp-westus3

Proprietà di build proprietà dell'oggetto

Proprietà Richiesto Digitare Description
reteConnessione Stringa Seleziona la connessione di rete da utilizzare per le build delle immagini.

networkConnection

(corda)

Specifica la connessione di rete utilizzata durante la creazione dell'immagine. Usa questa impostazione quando i compiti di build necessitano di accesso a risorse come repository privati o account di storage raggiungibili solo tramite una specifica connessione di rete. La connessione di rete deve essere collegata al centro sviluppatori prima di poterla usare per la creazione delle immagini.

buildProperties:
  networkConnection: my-westus3

Attività integrate

Usa i compiti integrati quando hai bisogno di azioni di personalizzazione comuni senza allegare un catalogo. Usa il ~/ prefisso per chiamare un compito integrato, ad esempio ~/winget, ~/powershell, o ~/gitclone.

Compito integrato in GitClone

Usa il compito integrato di GitClone per clonare un repository nella dev box.

Esempio:

tasks:
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/microsoft/calculator
      directory: C:\Workspaces
      branch: main
Proprietà Richiesto Digitare Description
repositoryUrl ✅ Stringa Specifica l'URL del repository da clonare.
directory Stringa Imposta la directory sotto cui il repository è clonato.
ramo Stringa Seleziona un ramo da clonare.
Pat Stringa Fornisce un token di accesso personale per operazioni di clonazione autenticate.

repositoryUrl

(corda, necessaria)

Specifica l'URL del repository da clonare.

directory

(stringa, predefinita: C:\Workspaces)

Imposta la directory sotto cui il repository è clonato.

branch

(corda)

Seleziona un ramo da clonare.

pat

(corda)

Fornisce un token di accesso personale per operazioni di clonazione autenticate. Quando pat non viene fornito, il clone viene messo in coda per il primo accesso dell'utente. Quando fornisci pat, il compito può essere clonato durante il provisioning. Usa un riferimento segreto Key Vault invece di un valore segreto grezzo.

Il compito integrato di GitClone installa anche PowerShell 7, Git e Git LFS durante l'esecuzione.

Attività predefinita di PowerShell

Usa il task integrato di PowerShell per eseguire un comando o uno script.

Esempio:

tasks:
  - name: ~/powershell
    parameters:
      command: Write-Host "Hello from Dev Box"
Proprietà Richiesto Digitare Description
command Stringa Esegue un comando in linea.
Directory di lavoro Stringa Imposta la directory di lavoro per il comando o lo script.
copione Stringa Esegue uno script PowerShell locale o remoto.
scriptArgs Stringa Fornisce argomentazioni per la sceneggiatura.
scriptExecutionPolicy Stringa Imposta la policy di esecuzione dello script.

command

(corda)

Esegue un comando in linea. Se fornisci command, i scriptparametri , scriptArgs, e scriptExecutionPolicy vengono ignorati.

workingDirectory

(corda)

Imposta la directory di lavoro per il comando o lo script.

script

(corda)

Specifica il percorso verso uno script PowerShell locale o remoto da eseguire. Questo parametro viene ignorato quando command viene fornito.

scriptArgs

(corda)

Fornisce argomentazioni per la sceneggiatura. Questo parametro viene ignorato quando command viene fornito.

scriptExecutionPolicy

(stringa, predefinita: Bypass)

Imposta la policy di esecuzione dello script. Questo parametro viene ignorato quando command viene fornito.

Attività predefinita WinGet

Usa il compito integrato di WinGet per installare direttamente un pacchetto o applica un file di configurazione WinGet.

Importante

Il compito integrato di WinGet non è lo stesso dell'eseguibile winget . Il compito integrato utilizza il cmdlet PowerShell WinGet.

Esempio:

tasks:
  - name: ~/winget
    parameters:
      package: GitHub.GitHubDesktop
      version: 3.4.16
Proprietà Richiesto Digitare Description
Fileconfigurazione Stringa Punta a un file di configurazione locale di WinGet.
downloadUrl Stringa Scarica un file di configurazione da un URL pubblico.
inlineConfigurationBase64 Stringa Fornisce un file di configurazione WinGet codificato in Base64.
package Stringa Installa un pacchetto direttamente per nome.
version Stringa Installa una versione specifica del pacchetto.

configurationFile

(corda)

Punta a un file YAML di configurazione WinGet sulla macchina locale.

downloadUrl

(corda)

Specifica un URL pubblico per un file YAML di configurazione WinGet. Il file viene scaricato sul percorso in configurationFile.

inlineConfigurationBase64

(corda)

Fornisce un file YAML di configurazione WinGet codificato in Base64. Il compito lo decodifica in configurationFile, o in un file temporaneo se configurationFile non è impostato.

package

(corda)

Installa un pacchetto direttamente per nome. Se usi una sorgente di file di configurazione, non è necessario fornire package.

version

(corda)

Installa una versione specifica del pacchetto. Se usi una sorgente di file di configurazione, non è necessario fornire version.

File task.yaml

Da usare task.yaml per definire un compito di personalizzazione riutilizzabile in un catalogo. Una definizione di task descrive il comando, i metadati, i parametri, la documentazione e le impostazioni di esecuzione per il task.

Quando definisci i compiti di personalizzazione, identifichi i compiti disponibili per gli sviluppatori per l'uso nei imagedefinition.yaml file o devbox.yaml file. Puoi usare definizioni di task per limitare azioni ad alto privilegio, come la possibilità di eseguire comandi PowerShell arbitrari.

Esempio di file 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

Il seguente esempio mostra una definizione di compito che esegue un comando PowerShell in una specifica directory di lavoro:

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

Proprietà Task.yaml

Proprietà Richiesto Digitare Description
$schema ✅ Stringa Specifica la versione dello schema per il file di attività.
name ✅ Stringa Definisce l'identificatore del compito.
command ✅ Stringa Fornisce il comando PowerShell che implementa il compito.
description Stringa Descrive il compito.
autore Stringa Identifica l'autore del compito.
issueNotificaEmail Stringa Fornisce un'email di contatto per problemi di attività.
documentationURL Stringa Collegamenti alla documentazione delle attività.
licenseURL Stringa Collegamenti alla licenza del compito.
Parole chiave matrice di stringhe Lista le parole chiave di ricerca per il compito.
Parametri object Definisce gli input che il compito accetta.
timeout Intero Imposta il timeout predefinito in pochi minuti.
documentazione. object Aggiunge note ed esempi di invocazioni di compiti per i consumatori.
riavvioRichiesto Boolean Indica se il compito richiede un riavvio dopo l'esecuzione.

$schema

(corda, necessaria)

Specifica la versione dello schema per la definizione del compito. Gli esempi attuali usano 1.0.

name

(corda, necessaria)

Definisce l'identificatore utilizzato per fare riferimento al compito da imagedefinition.yaml o devbox.yaml file. Il nome deve essere univoco nel contesto del catalogo in cui è presente l'attività.

Usa gli stessi vincoli di denominazione degli altri artefatti di personalizzazione di Dev Box. Il nome deve avere tra 3 e 63 caratteri, iniziare con un carattere alfanumerico e contenere solo caratteri alfanumerici, -, ., o _. Il / carattere è riservato.

name: install-vsix-extension

command

(corda, necessaria)

Specifica il comando PowerShell che implementa il compito. Il comando viene eseguito in Windows PowerShell sulla macchina locale. Usa {{parameterName}} la sintassi per fare riferimento ai valori dei parametri nella stringa di comando.

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

Per esempio:

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

description

(corda)

Descrive lo scopo del compito.

description: This task executes a PowerShell command.

author

(corda)

Identifica l'autore del compito per audit e risoluzione dei problemi.

author: Contoso Corporation

issueNotificationEmail

(corda)

Fornisce un indirizzo email che gli utenti possono contattare se hanno problemi con il compito. La funzionalità del prodotto non consuma questo valore.

documentationURL

(corda)

Link alla documentazione per il compito.

documentationURL: https://link.to/documentation

licenseURL

(corda)

Collegamenti alla licenza del compito.

licenseURL: https://link.to/license

keywords

(schiera di corde)

Elenca parole chiave che aiutano i consumatori a trovare il compito.

parameters

(oggetto)

Definisce parametri di input nominati per il compito. Ogni elemento figlio rappresenta un nome di parametro e può definire il tipo di parametro, i valori consentiti, il valore predefinito, la descrizione, le regole di validazione, i limiti di lunghezza e se il parametro è richiesto.

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

Proprietà della definizione dei parametri

Proprietà Richiesto Digitare Description
tipo ✅ Stringa Specifica il tipo di dato di ingresso.
consentito matrice di stringhe Restringe l'ingresso a una lista fissa di valori della stringa.
default stringa, booleana o numero Imposta il valore predefinito per l'input.
description Stringa Descrive l'input.
validazioneRegex Stringa Valida i valori della stringa rispetto a un'espressione regolare.
minLength Intero Imposta la lunghezza minima per i valori della stringa.
maxLength Intero Imposta la lunghezza massima per i valori della stringa.
required Boolean Indica se l'input deve essere fornito.

type

(stringa, obbligatoria, valori consentiti: stringa, booleana, numero)

Specifica il tipo di dato di ingresso.

allowed

(schiera di corde)

Restringe l'ingresso a un insieme fisso di valori di stringa consentiti.

default

(stringa, booleana o numero)

Imposta il valore predefinito per l'input.

description

(corda)

Descrive l'input.

validationRegex

(corda)

Definisce un'espressione regolare che i valori della stringa devono corrispondere.

minLength

(intero)

Imposta la lunghezza minima per i valori della stringa.

maxLength

(intero)

Imposta la lunghezza massima per i valori della stringa.

required

(booleano)

Indica se l'input deve essere fornito. Se omesso, il valore predefinito è false.

timeout

(intero, predefinito: 30)

Imposta il timeout predefinito del compito in pochi minuti. Se non specifichi un valore, il valore predefinito è 30 minuti.

timeout: 30

documentation

(oggetto)

Fornisce note ed esempi di invocazioni che i consumatori di task possono utilizzare quando aggiungono il task a una definizione di immagine.

Proprietà dell'oggetto documentazione

Proprietà Richiesto Digitare Description
Note Stringa Fornisce indicazioni ai consumatori del compito.
Esempi Array degli oggetti task Mostra come invocare il compito da un file YAML.

notes

(corda)

Aggiunge indicazioni o avvertenze per i consumatori del compito.

examples

(array di oggetti di attività)

Mostra esempi di invocazioni di task utilizzando lo stesso schema delle voci di task in imagedefinition.yaml.

rebootRequired

(booleano, predefinito: falso)

Indica se il compito richiede un riavvio dopo l'esecuzione.

Contenuti correlati

  • Last updated on