Özelleştirmeler şema başvurusu

Microsoft Dev Box özelleştirmeleri, platform mühendisleri ve geliştiricilerin YAML dosyalarını kullanarak araçları ön yüklemeleri, depoları klonlamasını ve dev box'larda ayarları yapılandırmasını sağlar. Bu referans, Dev Box özelleştirmelerinin desteklediği YAML dosyaları ve yerleşik görevler için mevcut şemayı tanımlar.

Bu referansı ihtiyacınız olduğunda kullanın:

• imagedefinition.yaml veya task.yaml dosyasında geçerli olan özellikleri, türleri ve varsayılanları arayın.
• Yerleşik ~/gitclone, ~/powershell, ve ~/winget görevlerin kabul ettiği parametreleri onaylayın.
• Dev Box bir görsel sağladığında veya bir dev box'a özelleştirmeler uyguladığında , userTasks, , variablesparameters, ve buildProperties nasıl tasksbirlikte çalıştığını anlayın.

Özelleştirme dosya türleri

Dev Box özelleştirmeleri, her biri farklı bir amaç ve hedef kitlesi olan üç YAML dosya türü kullanır:

Dahili ~/gitclone, ~/powershell, ve ~/winget görevler herhangi bir geliştirme merkezinden katalog eklemeden temin edilebilir. Bu yerleşik görevlerin ötesine özel görevler eklemek için, bunları katalogdaki dosyalarda task.yaml tanımlayın ve resim tanımınız veya kullanıcı özelleştirme dosyanızdan isimleriyle çağırın. Daha fazla bilgi için Microsoft Dev Box özelleştirmelerine bakınız.

Imagedefinition.yaml dosyaları

Dev Box'un bir görüntü tanımı oluştururken uyguladığı görsel, parametreler, değişkenler ve özelleştirme görevlerini tanımlamak için kullanılır imagedefinition.yaml .

Örnek imagedefinition.yaml dosyası

$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 özellikleri

$schema

(ip veya numara)

Dosyanın şema sürümünü belirtir. Güncel örnekler .1.0

$schema: "1.0"

name

(dize, zorunlu, 3-63 karakter)

Bir resim tanımı seçtiğinizde gösterilen dost ismi belirtir. Bu ayar, havuzları oluşturduğunuzda ve güncelleştirdiğinizde kullanılabilen görüntü tanımının adını denetler. İsim, , ", , , :, ,@|&*;?<=+>boşluk /veya ile başlayamaz.-_][

name: example-image-definition

description

(ip)

Görüntü tanımının amacını tanımlar.

description: Install core tools and clone the project repository.

image

(ip, zorunlu)

Dev box görüntüsü için kullanılacak temel görüntüyü belirler. Görüntü, bir pazar yeri görüntüsü veya ekli bir Azure Compute Gallery'den özel bir görüntü olabilir ve formatında gallery-name/image-name@version.

Examples:

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

image: my-gallery/my-image@0.0.1

Azure Compute Gallery eklemek için Configure Azure Compute Gallery for Microsoft Dev Box bölümüne bakınız.

Geliştirici merkezinizin erişebileceği görsellerin listesini almak için Azure CLI kullanın:

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

Gerekirse, önce Dev Center Azure CLI uzantısını yükleyin:

az extension add --name devcenter

parameters

(nesne)

Görevlerde referans verebileceğiniz adlandırılmış giriş parametrelerini tanımlar.{{parameterName}}

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

Parametre nesne özellikleri

type

(dize, gerekli, izin verilen değerler: dize, boolean, sayı)

Parametre veri türünü belirtir.

allowed

(iplik dizisi)

Parametreyi izin verilen sabit bir dizi dizi ile sınırlar.

default

(dize, boolean veya sayı, gereklidir)

Parametrenin varsayılan değerini ayarlıyor.

description

(ip)

Yazarlar ve araçlar için parametreyi tanımlar.

validationRegex

(ip)

Dizide değerlerinin eşleşmesi gereken bir düzenli ifade tanımlar.

minLength

(tam sayı)

Dizi değerleri için minimum uzunlukları belirler.

maxLength

(tam sayı)

Dizi değerleri için maksimum uzunlukları belirler.

variables

(nesne)

Resim tanımında yeniden kullanabileceğiniz adlandırılmış değişkenleri tanımlar.

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

Değişken nesne özellikleri

type

(dize, gerekli, izin verilen değerler: dize, boolean, sayı)

Değişken veri türünü belirtir.

value

(dize, boolean veya sayı, gereklidir)

Değişken değerini belirler.

description

(ip)

Yazarlar ve araçlar için değişkeni tanımlar.

tasks

(görev nesneleri dizisi)

Sağlama sırasında sistem bağlamında çalıştırılacak özelleştirme görevlerini listeler. Sağladığınız özel giriş değerleri göreve göre değişir. Her görev girişi nameparametersdisplayNamedescription, ve .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

Özellik timeout isteğe bağlıdır ve kullandığınızda imagedefinition.yamlsaniyelerle ölçülür.

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

Görev girişi özellikleri

name

(ip, zorunlu)

Yürütülecek görevi belirler. Yerleşik görevler için ön ~/ eki kullanın, örneğin ~/winget, ~/powershell, ve ~/gitclone.

displayName

(ip)

Arayüz yüzeyleri için kısa ekran metni sağlar.

description

(ip)

Görevin görüntü tanımında ne yaptığını açıklar.

parameters

(nesne)

Göreve iletilen giriş değerlerini tanımlar. Parametre isimleri ve değer türleri seçilen göreve bağlıdır.

Parametre tanımları, parametre özellikleri için tanımlanan task.yaml aynı şemayı takip eder. Detaylar için bkz. type, allowed, default, description, maxLengthvalidationRegexminLength, ve required.

timeout

(tam sayı)

Görev yürütme süresini saniyeler içinde geçersiz kılar.

userTasks

(görev nesneleri dizisi)

Giriş sonrası kullanıcı bağlamında çalıştırılacak özelleştirme görevlerini listeler. userTasks Aynı görev girişi şemasını kullanır tasks.

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

buildProperties

(nesne)

Görüntü oluşturma sürecini özelleştiren yapıya özgü ayarları tanımlar.

buildProperties:
  networkConnection: corp-westus3

Yapı özellikleri nesne özellikleri

networkConnection

(ip)

Görüntü oluşturulurken kullanılan ağ bağlantısını belirtir. Bu ayarı, sadece belirli bir ağ bağlantısı üzerinden erişilebilen özel depolar veya depolama hesapları gibi kaynaklara erişim gerektirdiğinde kullanın. Ağ bağlantısı, görüntü oluşturmak için kullanılmadan önce geliştirme merkezine bağlı olmalıdır.

buildProperties:
  networkConnection: my-westus3

Yerleşik görevler

Ortak özelleştirme işlemlerine ihtiyacınız olduğunda katalog eklemeden yerleşik görevleri kullanın. Yerleşik bir görevi çağırmak için önek ~/ kullanın, örneğin ~/winget, , ~/powershell, veya ~/gitclone.

• GitClone yerleşik görevi
• PowerShell yerleşik görevi
• WinGet yerleşik görevi

GitClone yerleşik görevi

GitClone yerleşik görevini kullanarak bir depoyu geliştirici kutusuna klonlayın.

Örnek:

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

repositoryUrl

(ip, zorunlu)

Klonlanacak depo URL'sini belirtir.

directory

(dizimiz, varsayılan: C:\Workspaces)

Deponun klonlandığı dizini ayarlar.

branch

(ip)

Klonlamak için bir dal seçer.

pat

(ip)

Kimlik doğrulamalı klon işlemleri için kişisel erişim tokenı sağlar. Sunulmadığında pat , klon ilk kullanıcı giriş için sıraya alınır. Tedarik patettiğinizde, görev tedarik sırasında klonlanabilir. Ham bir gizli değer yerine Key Vault gizli referansı kullanın.

GitClone yerleşik görevi, çalıştırma sırasında PowerShell 7, Git ve Git LFS'yi de yükler.

PowerShell yerleşik görevi

PowerShell yerleşik görevini kullanarak bir komut veya betik çalıştırın.

Örnek:

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

command

(ip)

Bir hat içi komut çalıştırır. Eğer , commandscriptscriptArgsscriptExecutionPolicy , ve parametreler göz ardı edilir.

workingDirectory

(ip)

Komut veya betik için çalışma dizinini ayarlar.

script

(ip)

Çalıştırılacak yerel veya uzak PowerShell betiği yolunu belirtir. Bu parametre sağlandığında command göz ardı edilir.

scriptArgs

(ip)

Senaryo için argümanlar sunar. Bu parametre sağlandığında command göz ardı edilir.

scriptExecutionPolicy

(dize, varsayılan: Bypass)

Script için yürütme politikasını belirler. Bu parametre sağlandığında command göz ardı edilir.

WinGet yerleşik görevi

WinGet yerleşik görevini kullanarak doğrudan bir paket yükleyin veya bir WinGet yapılandırma dosyası uygulayın.

Örnek:

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

configurationFile

(ip)

Yerel makinedeki bir WinGet yapılandırma YAML dosyasına işaret ediyor.

downloadUrl

(ip)

WinGet yapılandırma YAML dosyası için genel bir URL belirtir. Dosya, yola indirilir configurationFile.

inlineConfigurationBase64

(ip)

Base64 kodlu WinGet yapılandırma YAML dosyası sağlar. Görev bunu , configurationFileya da ayarlanmadıysa configurationFile geçici bir dosyaya kod açar.

package

(ip)

Bir paketi doğrudan ismine göre yükler. Bir yapılandırma dosyası kaynağı kullanıyorsanız, package.

version

(ip)

Belirli bir paket sürümünü yükler. Bir yapılandırma dosyası kaynağı kullanıyorsanız, version.

task.yaml dosyaları

Bir katalogda yeniden kullanılabilir özelleştirme görevini tanımlamak için kullanılır task.yaml . Görev tanımı, görev için komut, meta veriler, parametreler, dokümantasyon ve yürütme ayarlarını tanımlar.

Özelleştirme görevlerini tanımlarken, geliştiricilerin dosyalarda imagedefinition.yamldevbox.yaml kullanabileceği görevleri belirlersiniz. Görev tanımlarını, keyfi olarak PowerShell komutlarını çalıştırma gibi yüksek ayrıcalıklı eylemleri kısıtlamak için kullanabilirsiniz.

Örnek task.yaml dosyası

$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

Aşağıdaki örnek, belirli bir çalışma dizininde PowerShell komutunu çalıştıran bir görev tanımını gösterir:

$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

(ip, zorunlu)

Görev tanımı için şema sürümünü belirtir. Güncel örnekler .1.0

name

(ip, zorunlu)

Göreve referans vermek için kullanılan tanımlayıcıyı veya imagedefinition.yamldevbox.yaml dosyaları tanımlar. Adın, görevin bulunduğu katalog bağlamında benzersiz olması gerekir.

Diğer Dev Box özelleştirme eserleriyle aynı adlandırma kısıtlamalarını kullanın. İsim 3 ile 63 karakter arasında olmalı, alfanumerik bir karakterle başlamalı ve yalnızca alfanumerik karakterler, -, ., veya _içermelidir. Karakter / ayrılmıştır.

name: install-vsix-extension

command

(ip, zorunlu)

Görevi uygulayan PowerShell komutunu belirtir. Komut, yerel makinede Windows PowerShell'de çalışır. Komut dizisinde parametre değerlerine referans vermek için sözdizimi kullanın {{parameterName}} .

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

Örneğin:

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

description

(ip)

Görevin amacını açıklar.

description: This task executes a PowerShell command.

author

(ip)

Denetimler ve sorun giderme için görev yazarını belirler.

author: Contoso Corporation

issueNotificationEmail

(ip)

Kullanıcıların görevle ilgili sorunları varsa iletişime geçebileceği bir e-posta adresi sağlar. Ürün işlevselliği bu değeri tüketmez.

documentationURL

(ip)

Görevle ilgili dokümantasyon bağlantıları.

documentationURL: https://link.to/documentation

licenseURL

(ip)

Görev lisansına bağlantılar.

licenseURL: https://link.to/license

keywords

(iplik dizisi)

Tüketicilerin görevi bulmasına yardımcı olan anahtar kelimeleri listeler.

parameters

(nesne)

Görev için adlandırılmış giriş parametrelerini tanımlar. Her alt öğe bir parametre adını temsil eder ve parametre türünü, izin verilen değerleri, varsayılan değeri, açıklamayı, doğrulama kurallarını, uzunluk sınırlarını ve parametrenin gerekli olup olmadığını tanımlayabilir.

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

Parametre tanımı özellikleri

type

(dize, gerekli, izin verilen değerler: dize, boolean, sayı)

Giriş veri tipini belirtir.

allowed

(iplik dizisi)

Girişi, izin verilen sabit bir dizi değeriyle sınırlar.

default

(dizi, boolean veya sayı)

Giriş için varsayılan değeri belirler.

description

(ip)

Girişi tanımlar.

validationRegex

(ip)

Dizide değerlerinin eşleşmesi gereken bir düzenli ifade tanımlar.

minLength

(tam sayı)

Dizi değerleri için minimum uzunlukları belirler.

maxLength

(tam sayı)

Dizi değerleri için maksimum uzunlukları belirler.

required

(boolean)

Girdinin sağlanması gerekip gerekmediğini gösterir. Atlanırsa, varsayılan değer olur false.

timeout

(tam sayı, varsayılan: 30)

Varsayılan görev süresini dakikalar içinde ayarlar. Bir değer belirtmezseniz, varsayılan süre 30 dakikadır.

timeout: 30

documentation

(nesne)

Görev kullanıcılarının görevi bir görüntü tanımına eklerken kullanabilecekleri notlar ve çağrı örnekleri sunar.

Dokümantasyon nesnesi özellikleri

notes

(ip)

Görevin tüketicileri için rehberlik veya uyarılar ekliyor.

examples

(görev nesneleri dizisi)

Görev çağrılarının örneklerini gösterir, aynı şemayı kullanarak .imagedefinition.yaml

rebootRequired

(Boolean, varsayılan: yanlış)

Görevin çalıştırıldıktan sonra yeniden başlatma gerektirip gerektirmediğini gösterir.

İlgili içerik

• Takım özelleştirmelerini yapılandırmak - Dosyalar oluşturun imagedefinition.yaml ve bunları bir dev box havuzuna uygulayın.
• Geliştirici kutunuz için kullanıcı özelleştirme dosyası yapılandırın - Kişisel devbox.yaml bir dosya yazın ve yükleyin.
• Dev Box özelleştirmeleri için görevleri yapılandırmak - Dosyaları yazar task.yaml ve katalog aracılığıyla yayınlayın.
• Azure kaynaklarına bağlanma veya özel depoları kopyalama