Buat artefak kustom untuk DevTest Labs

Artikel ini menjelaskan cara membuat file artefak khusus untuk mesin virtual (VM) Azure DevTest Labs. Artefak DevTest Labs menentukan tindakan yang harus diambil untuk menyediakan VM. Artefak terdiri dari file definisi artefak dan file skrip lainnya yang disimpan dalam folder di repositori Git.

File definisi artefak

File definisi artefak terdiri dari ekspresi JSON yang menentukan apa yang ingin Anda instal pada VM. File ini menentukan nama artefak, perintah untuk dijalankan, dan parameter yang tersedia untuk perintah. Anda dapat merujuk ke file skrip lain dalam file definisi artefak berdasarkan nama.

Contoh berikut menunjukkan bagian yang membentuk struktur dasar file definisi artifak artifactfile.json:

  {
    "$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
    "title": "",
    "description": "",
    "iconUri": "",
    "targetOsType": "",
    "parameters": {
      "<parameterName>": {
        "type": "",
        "displayName": "",
        "description": ""
      }
    },
    "runCommand": {
      "commandToExecute": ""
    }
  }
Nama elemen Deskripsi
$schema Lokasi file skema JSON. File skema JSON dapat membantu Anda menguji validitas file definisi.
title Nama artefak yang ditampilkan di laboratorium. Diperlukan.
description Nama artefak yang ditampilkan di laboratorium. Diperlukan.
iconUri URI ikon artefak yang ditampilkan di laboratorium.
targetOsType Sistem operasi VM tempat menginstal artefak. Nilai yang didukung: Windows, Linux. Diperlukan.
parameters Nilai untuk menyesuaikan artefak saat menginstal pada VM.
runCommand Perintah instalasi artefak untuk dijalankan pada VM. Diperlukan.

Parameter artefak

Di bagian parameter file definisi, tentukan nilai yang dapat dimasukkan pengguna ketika mereka memasang artefak. Anda dapat merujuk ke nilai-nilai ini dalam perintah pemasangan artefak.

Untuk menentukan parameter, gunakan struktur berikut:

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }
Nama elemen Deskripsi
type Jenis nilai parameter. Diperlukan.
displayName Nama parameter yang akan ditampilkan ke pengguna lab. Diperlukan.
description Deskripsi parameter yang akan ditampilkan ke pengguna lab. Diperlukan.

Tipe nilai parameter yang diizinkan adalah:

Jenis Deskripsi
string String JSON yang valid
int Bilangan bulat JSON yang valid
bool Boolean JSON yang valid
array Array JSON yang valid

Rahasia sebagai string aman

Untuk menyatakan rahasia sebagai parameter string aman dengan karakter bertopeng di UI, gunakan sintaks berikut di bagian parameters file artifactfile.json :


    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "Any text string is allowed, including spaces, and will be presented in UI as masked characters.",
      "allowEmpty": false
    },

Perintah pemasangan artefak untuk menjalankan skrip PowerShell mengambil string aman yang dibuat menggunakan perintah ConvertTo-SecureString.

  "runCommand": {
    "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./artifact.ps1 -StringParam ''', parameters('stringParam'), ''' -SecureStringParam (ConvertTo-SecureString ''', parameters('securestringParam'), ''' -AsPlainText -Force) -IntParam ', parameters('intParam'), ' -BoolParam:$', parameters('boolParam'), ' -FileContentsParam ''', parameters('fileContentsParam'), ''' -ExtraLogLines ', parameters('extraLogLines'), ' -ForceFail:$', parameters('forceFail'), '\"')]"
  }

Jangan mencatat rahasia ke konsol, karena skrip menangkap output untuk debugging pengguna.

Ekspresi dan fungsi artefak

Anda dapat menggunakan ekspresi dan fungsi untuk membuat perintah pemasangan artefak. Ekspresi mengevaluasi ketika artefak diinstal. Ekspresi dapat muncul di mana saja dalam nilai string JSON, dan selalu mengembalikan nilai JSON lain. Lampirkan ekspresi dengan tanda kurung, [ ]. Jika Anda perlu menggunakan string literal yang dimulai dengan tanda kurung, gunakan dua tanda kurung [[.

Biasanya, Anda menggunakan ekspresi dengan fungsi untuk membangun nilai. Panggilan fungsi diformat sebagai functionName(arg1, arg2, arg3).

Fungsi umum meliputi:

Fungsi Deskripsi
parameters(parameterName) Mengembalikan nilai parameter untuk diberikan saat perintah artefak berjalan.
concat(arg1, arg2, arg3, ...) Menggabungkan beberapa nilai string. Fungsi ini dapat mengambil berbagai argumen.

Contoh berikut menunjukkan cara menggunakan ekspresi dan fungsi untuk membuat nilai:

  runCommand": {
      "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./startChocolatey.ps1'
  , ' -RawPackagesList ', parameters('packages')
  , ' -Username ', parameters('installUsername')
  , ' -Password ', parameters('installPassword'))]"
  }

Membuat artefak kustom

Membuat artefak kustom:

  • Instal editor JSON untuk bekerja dengan file definisi artefak. Visual Studio Code tersedia untuk Windows, Linux, dan macOS.

  • Mulai dengan file definisi artifactfile.json sampel.

    Repositori artefak DevTest Labs publik memiliki pustaka artefak yang kaya yang dapat Anda gunakan. Anda dapat mengunduh file definisi artefak dan mengkustomnya untuk membuat artefak Anda sendiri.

    Artikel ini menggunakan file definisi artifactfile.json dan skrip PowerShell artifact.ps1 pada https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

  • Gunakan IntelliSense untuk melihat elemen dan opsi nilai yang valid yang dapat Anda gunakan untuk membuat file definisi artefak. Misalnya, saat Anda mengedit elemen targetOsType, IntelliSense menunjukkan pilihan Windows da Linux.

  • Simpan artefak Anda di repositori artefak Git publik atau privat.

    • Simpan setiap file definisi artefak artifactfile.json dalam direktori terpisah yang diberi nama sama dengan nama artefak.
    • Simpan skrip yang direferensikan perintah penginstalan di direktori yang sama dengan file definisi artefak.

    Tangkapan layar berikut menunjukkan folder contoh artefak:

    Screenshot that shows an example artifact folder.

  • Untuk menyimpan artefak kustom Anda di repositori artefak DevTest Labs publik, buka permintaan tarik terhadap repositori tersebut.

  • Untuk menambahkan repositori artefak pribadi Anda ke lab, lihat Menambahkan repositori artefak ke lab Anda di DevTest Labs.

Langkah berikutnya