Udostępnij za pośrednictwem

Tworzenie niestandardowych artefaktów dla usługi DevTest Labs

  • Artykuł

W tym artykule opisano sposób tworzenia niestandardowych plików artefaktów dla maszyn wirtualnych Azure DevTest Labs. Artefakty usługi DevTest Labs określają akcje do wykonania w celu aprowizacji maszyny wirtualnej. Artefakt składa się z pliku definicji artefaktu i innych plików skryptów przechowywanych w folderze w repozytorium Git.

Pliki definicji artefaktu

Pliki definicji artefaktu to wyrażenia JSON określające, co chcesz zainstalować na maszynie wirtualnej. Pliki definiują nazwę artefaktu, polecenie do uruchomienia i dostępne parametry dla polecenia. W pliku definicji artefaktu można odwoływać się do innych plików skryptów według nazwy.

Poniższy przykład przedstawia sekcje tworzące podstawową strukturę pliku definicji artefaktu 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": ""
    }
  }
Nazwa elementu Opis
$schema Lokalizacja pliku schematu JSON. Plik schematu JSON może pomóc w przetestowaniu ważności pliku definicji.
title Nazwa artefaktu do wyświetlenia w laboratorium. Wymagane.
description Opis artefaktu do wyświetlenia w laboratorium. Wymagane.
iconUri Identyfikator URI ikony artefaktu do wyświetlenia w laboratorium.
targetOsType System operacyjny maszyny wirtualnej do zainstalowania artefaktu. Obsługiwane wartości: Windows, Linux. Wymagane.
parameters Wartości do dostosowania artefaktu podczas instalowania na maszynie wirtualnej.
runCommand Polecenie instalacji artefaktu do wykonania na maszynie wirtualnej. Wymagane.

Parametry artefaktu

W sekcji parameters pliku definicji określ wartości, które użytkownik może wprowadzić podczas instalowania artefaktu. Możesz odwołać się do tych wartości w poleceniu instalacji artefaktu.

Aby zdefiniować parametry, użyj następującej struktury:

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }
Nazwa elementu Opis
type Typ wartości parametru. Wymagane.
displayName Nazwa parametru do wyświetlenia użytkownikowi laboratorium. Wymagane.
description Opis parametru do wyświetlenia użytkownikowi laboratorium. Wymagane.

Dozwolone typy wartości parametrów to:

Typ Opis
string Dowolny prawidłowy ciąg JSON
int Dowolna prawidłowa liczba całkowita JSON
bool Dowolna prawidłowa wartość logiczna JSON
array Dowolna prawidłowa tablica JSON

Wpisy tajne jako bezpieczne ciągi

Aby zadeklarować wpisy tajne jako parametry bezpiecznego ciągu z zamaskowanych znaków w interfejsie użytkownika, użyj następującej składni w parameters sekcji pliku 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
    },

Polecenie instalacji artefaktu służące do uruchamiania skryptu programu PowerShell pobiera bezpieczny ciąg utworzony przy użyciu ConvertTo-SecureString polecenia .

  "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'), '\"')]"
  }

Nie rejestruj wpisów tajnych w konsoli, ponieważ skrypt przechwytuje dane wyjściowe na potrzeby debugowania użytkownika.

Wyrażenia artefaktów i funkcje

Możesz użyć wyrażeń i funkcji, aby skonstruować polecenie instalacji artefaktu. Wyrażenia są obliczane podczas instalowania artefaktu. Wyrażenia mogą być wyświetlane w dowolnym miejscu w wartości ciągu JSON i zawsze zwracają inną wartość JSON. Ujęcie wyrażeń za pomocą nawiasów kwadratowych [ ]. Jeśli musisz użyć ciągu literału rozpoczynającego się nawiasem kwadratowym, użyj dwóch nawiasów [[.

Zwykle używasz wyrażeń z funkcjami do konstruowania wartości. Wywołania funkcji są formatowane jako functionName(arg1, arg2, arg3).

Typowe funkcje to:

Funkcja Opis
parameters(parameterName) Zwraca wartość parametru, aby podać, gdy zostanie uruchomione polecenie artefaktu.
concat(arg1, arg2, arg3, ...) Łączy wiele wartości ciągów. Ta funkcja może przyjmować różne argumenty.

W poniższym przykładzie użyto wyrażeń i funkcji do konstruowania wartości:

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

Tworzenie artefaktu niestandardowego

Aby utworzyć artefakt niestandardowy:

  • Zainstaluj edytor JSON, aby pracować z plikami definicji artefaktów. Visual Studio Code jest dostępna dla systemów Windows, Linux i macOS.

  • Rozpocznij od przykładowego pliku definicji artifactfile.json .

    Publiczne repozytorium artefaktów usługi DevTest Labs zawiera bogatą bibliotekę artefaktów, których można użyć. Możesz pobrać plik definicji artefaktu i dostosować go w celu utworzenia własnych artefaktów.

    W tym artykule użyto pliku definicji artifactfile.json i skryptu programu PowerShellartifact.ps1pod adresem https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

  • Użyj funkcji IntelliSense, aby wyświetlić prawidłowe elementy i opcje wartości, których można użyć do konstruowania pliku definicji artefaktu. Na przykład podczas edytowania targetOsType elementu funkcja IntelliSense wyświetla opcje Windows lub Linux .

  • Przechowuj artefakty w publicznych lub prywatnych repozytoriach artefaktów Git.

    • Przechowuj każdy plik definicji artefaktu artifactfile.json w osobnym katalogu o nazwie takiej samej jak nazwa artefaktu.
    • Zapisz skrypty, do których odwołuje się polecenie instalacji w tym samym katalogu co plik definicji artefaktu.

    Poniższy zrzut ekranu przedstawia przykładowy folder artefaktu:

    Zrzut ekranu przedstawiający przykładowy folder artefaktu.

  • Aby przechowywać niestandardowe artefakty w publicznym repozytorium artefaktów usługi DevTest Labs, otwórz żądanie ściągnięcia względem repozytorium.

  • Aby dodać prywatne repozytorium artefaktów do laboratorium, zobacz Dodawanie repozytorium artefaktów do laboratorium w usłudze DevTest Labs.

Następne kroki