Referensi skema kustomisasi

Penyesuaian Microsoft Dev Box memungkinkan insinyur dan pengembang platform menginstal alat terlebih dahulu, mengkloning repositori, dan mengonfigurasi pengaturan pada kotak pengembang dengan menggunakan file YAML. Referensi ini menjelaskan skema saat ini untuk file YAML dan tugas bawaan yang didukung oleh penyesuaian Dev Box.

Gunakan referensi ini saat Anda perlu:

• Cari properti, jenis, dan default yang valid dalam file imagedefinition.yaml atau task.yaml.
• Konfirmasikan parameter yang diterima oleh , ~/powershell, dan ~/winget tugas bawaan~/gitclone.
• Pahami bagaimana tasks, userTasks, , parametersvariables, dan buildProperties bekerja sama saat Dev Box menyediakan gambar atau menerapkan penyesuaian ke kotak pengembang.

Jenis file penyesuaian

Penyesuaian Dev Box menggunakan tiga jenis file YAML, masing-masing dengan tujuan dan audiens yang berbeda:

Built-in ~/gitclone, ~/powershell, dan ~/winget tugas tersedia dari pusat pengembangan mana pun tanpa melampirkan katalog. Untuk menambahkan tugas kustom di luar tugas bawaan tersebut, tentukan dalam task.yaml file dalam katalog dan panggil nama dari definisi gambar atau file penyesuaian pengguna. Untuk informasi selengkapnya, lihat Penyesuaian Microsoft Dev Box.

File imagedefinition.yaml

Gunakan imagedefinition.yaml untuk menentukan gambar, parameter, variabel, dan tugas penyesuaian yang diterapkan Dev Box saat membuat definisi gambar.

Contoh 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

Properti Imagedefinition.yaml

$schema

(string atau angka)

Menentukan versi skema untuk file. Contoh saat ini menggunakan 1.0.

$schema: "1.0"

name

(string, wajib, 3-63 karakter)

Menentukan nama yang cocok yang ditampilkan saat Anda memilih definisi gambar. Pengaturan ini mengontrol nama definisi gambar yang tersedia saat Anda membuat dan memperbarui kumpulan. Nama tidak boleh berisi /, ", [, *,-_]:|<>+=;,?@&

name: example-image-definition

description

(string)

Menjelaskan tujuan definisi gambar.

description: Install core tools and clone the project repository.

image

(string, wajib)

Menentukan gambar dasar yang akan digunakan untuk gambar kotak pengembang. Gambar dapat berupa gambar marketplace atau gambar kustom dari Azure Compute Gallery terlampir dalam format gallery-name/image-name@version.

Examples:

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

image: my-gallery/my-image@0.0.1

Untuk melampirkan Azure Compute Gallery, lihat Mengonfigurasi Azure Compute Gallery for Microsoft Dev Box.

Untuk mendapatkan daftar gambar yang dapat diakses oleh pusat pengembang Anda, gunakan Azure CLI:

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

Jika perlu, instal ekstensi Dev Center Azure CLI terlebih dahulu:

az extension add --name devcenter

parameters

(objek)

Menentukan parameter input bernama yang dapat Anda referensikan dalam tugas dengan menggunakan {{parameterName}} sintaks.

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

Properti objek parameter

type

(string, wajib, nilai yang diizinkan: string, boolean, number)

Menentukan jenis data parameter.

allowed

(array string)

Membatasi parameter ke kumpulan tetap nilai string yang diizinkan.

default

(string, boolean, atau angka, diperlukan)

Mengatur nilai default untuk parameter.

description

(string)

Menjelaskan parameter untuk penulis dan peralatan.

validationRegex

(string)

Menentukan ekspresi reguler yang harus cocok dengan nilai string.

minLength

(bilangan bulat)

Mengatur panjang minimum untuk nilai string.

maxLength

(bilangan bulat)

Mengatur panjang maksimum untuk nilai string.

variables

(objek)

Menentukan variabel bernama yang dapat Anda gunakan kembali dalam definisi gambar.

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

Properti objek variabel

type

(string, wajib, nilai yang diizinkan: string, boolean, number)

Menentukan jenis data variabel.

value

(string, boolean, atau angka, diperlukan)

Mengatur nilai variabel.

description

(string)

Menjelaskan variabel untuk penulis dan peralatan.

tasks

(array objek tugas)

Mencantumkan tugas penyesuaian untuk dijalankan dalam konteks sistem selama penyediaan. Nilai input spesifik yang Anda berikan bervariasi menurut tugas. Setiap entri tugas harus menyertakan name dan juga dapat menentukan displayName, description, parameters, dan 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

Properti ini timeout bersifat opsional dan diukur dalam detik saat Anda menggunakannya di imagedefinition.yaml.

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

Properti entri tugas

name

(string, wajib)

Mengidentifikasi tugas yang akan dijalankan. Gunakan ~/ awalan untuk tugas bawaan, seperti ~/winget, ~/powershell, dan ~/gitclone.

displayName

(string)

Menyediakan teks tampilan pendek untuk permukaan UI.

description

(string)

Menjelaskan apa yang dilakukan tugas dalam definisi gambar.

parameters

(objek)

Menentukan nilai input yang diteruskan ke tugas. Nama parameter dan jenis nilai bergantung pada tugas yang dipilih.

Definisi parameter mengikuti skema yang sama yang dijelaskan untuk task.yaml properti parameter. Untuk detailnya, lihat type, allowed, defaultminLengthmaxLengthdescriptionvalidationRegexdan .required

timeout

(bilangan bulat)

Mengganti batas waktu eksekusi tugas dalam hitungan detik.

userTasks

(array objek tugas)

Mencantumkan tugas penyesuaian untuk dijalankan dalam konteks pengguna setelah masuk. userTasks menggunakan skema entri tugas yang sama dengan tasks.

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

buildProperties

(objek)

Menentukan pengaturan khusus build yang menyesuaikan proses pembuatan gambar.

buildProperties:
  networkConnection: corp-westus3

Properti properti build

networkConnection

(string)

Menentukan koneksi jaringan yang digunakan selama pembuatan gambar. Gunakan pengaturan ini saat tugas build memerlukan akses ke sumber daya seperti repositori privat atau akun penyimpanan yang hanya dapat dijangkau melalui koneksi jaringan tertentu. Koneksi jaringan harus dilampirkan ke pusat pengembang sebelum Anda dapat menggunakannya untuk pembuatan gambar.

buildProperties:
  networkConnection: my-westus3

Tugas bawaan

Gunakan tugas bawaan saat Anda memerlukan tindakan penyesuaian umum tanpa melampirkan katalog. Gunakan ~/ awalan untuk memanggil tugas bawaan, misalnya ~/winget, ~/powershell, atau ~/gitclone.

• Tugas bawaan GitClone
• Tugas bawaan PowerShell
• Tugas bawaan WinGet

Tugas bawaan GitClone

Gunakan tugas bawaan GitClone untuk mengkloning repositori ke dalam kotak pengembang.

Contoh:

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

repositoryUrl

(string, wajib)

Menentukan URL repositori yang akan dikloning.

directory

(string, default: C:\Workspaces)

Mengatur direktori tempat repositori dikloning.

branch

(string)

Memilih cabang untuk dikloning.

pat

(string)

Menyediakan token akses pribadi untuk operasi klon yang diautentikasi. Jika pat tidak disediakan, klon akan diantri untuk login pengguna pertama. Saat Anda menyediakan pat, tugas dapat dikloning selama penyediaan. Gunakan referensi rahasia Key Vault alih-alih nilai rahasia mentah.

Tugas bawaan GitClone juga menginstal PowerShell 7, Git, dan Git LFS selama eksekusi.

Tugas bawaan PowerShell

Gunakan tugas bawaan PowerShell untuk menjalankan perintah atau skrip.

Contoh:

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

command

(string)

Menjalankan perintah sebaris. Jika Anda memberikan command, parameter script, scriptArgs, dan scriptExecutionPolicy akan diabaikan.

workingDirectory

(string)

Mengatur direktori kerja untuk perintah atau skrip.

script

(string)

Menentukan jalur ke skrip PowerShell lokal atau jarak jauh untuk dijalankan. Parameter ini diabaikan saat command disediakan.

scriptArgs

(string)

Menyediakan argumen untuk skrip. Parameter ini diabaikan saat command disediakan.

scriptExecutionPolicy

(string, default: Bypass)

Mengatur kebijakan eksekusi untuk skrip. Parameter ini diabaikan saat command disediakan.

Tugas bawaan WinGet

Gunakan tugas bawaan WinGet untuk menginstal paket secara langsung atau menerapkan file konfigurasi WinGet.

Contoh:

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

configurationFile

(string)

Menunjuk ke file YAML konfigurasi WinGet di komputer lokal.

downloadUrl

(string)

Menentukan URL publik untuk file YAML konfigurasi WinGet. File diunduh ke jalur di configurationFile.

inlineConfigurationBase64

(string)

Menyediakan file YAML konfigurasi WinGet yang dikodekan Base64. Tugas memecahkan kodenya ke configurationFile, atau ke file sementara jika configurationFile tidak diatur.

package

(string)

Menginstal paket langsung dengan nama. Jika Anda menggunakan sumber file konfigurasi, Anda tidak perlu menyediakan package.

version

(string)

Menginstal versi paket tertentu. Jika Anda menggunakan sumber file konfigurasi, Anda tidak perlu menyediakan version.

file task.yaml

Gunakan task.yaml untuk menentukan tugas penyesuaian yang dapat digunakan kembali dalam katalog. Definisi tugas menjelaskan perintah, metadata, parameter, dokumentasi, dan pengaturan eksekusi untuk tugas tersebut.

Saat menentukan tugas penyesuaian, Anda mengidentifikasi tugas yang tersedia bagi pengembang untuk digunakan dalam imagedefinition.yaml file atau devbox.yaml . Anda dapat menggunakan definisi tugas untuk membatasi tindakan hak istimewa tinggi, seperti kemampuan untuk menjalankan perintah PowerShell arbitrer.

Contoh 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

Contoh berikut menunjukkan definisi tugas yang menjalankan perintah PowerShell di direktori kerja tertentu:

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

Properti Task.yaml

$schema

(string, wajib)

Menentukan versi skema untuk definisi tugas. Contoh saat ini menggunakan 1.0.

name

(string, wajib)

Menentukan pengidentifikasi yang digunakan untuk mereferensikan tugas dari imagedefinition.yaml atau devbox.yaml file. Nama harus unik dalam konteks katalog tempat tugas berada.

Gunakan batasan penamaan yang sama dengan artefak penyesuaian Dev Box lainnya. Nama harus antara 3 dan 63 karakter, dimulai dengan karakter alfanumerik, dan hanya berisi karakter alfanumerik, -, ., atau _. Karakternya / dicadangkan.

name: install-vsix-extension

command

(string, wajib)

Menentukan perintah PowerShell yang mengimplementasikan tugas. Perintah berjalan di Windows PowerShell pada komputer lokal. Gunakan {{parameterName}} sintaks untuk mereferensikan nilai parameter dalam string perintah.

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

Contohnya:

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

description

(string)

Menjelaskan tujuan tugas.

description: This task executes a PowerShell command.

author

(string)

Mengidentifikasi penulis tugas untuk audit dan pemecahan masalah.

author: Contoso Corporation

issueNotificationEmail

(string)

Menyediakan alamat email yang dapat dihubungi pengguna jika mereka memiliki masalah dengan tugas tersebut. Fungsionalitas produk tidak menggunakan nilai ini.

documentationURL

(string)

Tautan ke dokumentasi untuk tugas tersebut.

documentationURL: https://link.to/documentation

licenseURL

(string)

Tautan ke lisensi tugas.

licenseURL: https://link.to/license

keywords

(array string)

Mencantumkan kata kunci yang membantu konsumen menemukan tugas.

parameters

(objek)

Menentukan parameter input bernama untuk tugas. Setiap item turunan mewakili nama parameter dan dapat menentukan jenis parameter, nilai yang diizinkan, nilai default, deskripsi, aturan validasi, batas panjang, dan apakah parameter diperlukan.

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

Properti definisi parameter

type

(string, wajib, nilai yang diizinkan: string, boolean, number)

Menentukan jenis data input.

allowed

(array string)

Membatasi input ke sekumpulan nilai string yang diizinkan.

default

(string, boolean, atau angka)

Mengatur nilai default untuk input.

description

(string)

Menjelaskan input.

validationRegex

(string)

Menentukan ekspresi reguler yang harus cocok dengan nilai string.

minLength

(bilangan bulat)

Mengatur panjang minimum untuk nilai string.

maxLength

(bilangan bulat)

Mengatur panjang maksimum untuk nilai string.

required

(Boolean)

Menunjukkan apakah input harus disediakan. Jika dihilangkan, defaultnya adalah false.

timeout

(bilangan bulat, default: 30)

Mengatur batas waktu tugas default dalam hitungan menit. Jika Anda tidak menentukan nilai, defaultnya adalah 30 menit.

timeout: 30

documentation

(objek)

Menyediakan catatan dan contoh pemanggilan yang dapat digunakan konsumen tugas saat mereka menambahkan tugas ke definisi gambar.

Properti objek dokumentasi

notes

(string)

Menambahkan panduan atau peringatan bagi konsumen tugas.

examples

(array objek tugas)

Menampilkan contoh pemanggilan tugas dengan menggunakan skema yang sama dengan entri tugas di imagedefinition.yaml.

rebootRequired

(Boolean, default: false)

Menunjukkan apakah tugas memerlukan reboot setelah eksekusi.

Konten terkait

• Mengonfigurasi penyesuaian tim - Buatimagedefinition.yaml file dan terapkan ke kumpulan kotak pengembang.
• Mengonfigurasi file penyesuaian pengguna untuk kotak pengembang Anda - Tulis dan upload file pribadi devbox.yaml .
• Mengonfigurasi tugas untuk penyesuaian Dev Box - Menulis task.yaml file dan menerbitkannya melalui katalog.
• Menyambungkan ke sumber daya Azure atau mengkloning repositori privat