Erstellen benutzerdefinierter Artefakte für DevTest Labs

  • Artikel

In diesem Artikel wird beschrieben, wie Sie benutzerdefinierte Artefaktdateien für Azure DevTest Labs-VMs erstellen. DevTest Labs-Artefakte geben Aktionen an, die zum Bereitstellen einer VM ausgeführt werden müssen. Ein Artefakt besteht aus einer Artefaktdefinitionsdatei und weiteren Skriptdateien, die in einem Ordner in einem Git-Repository gespeichert sind.

Artefaktdefinitionsdateien

Artefaktdefinitionsdateien bestehen aus JSON-Ausdrücken, die angeben, was Sie auf einer VM installieren möchten. Die Dateien definieren den Namen eines Artefakts, einen auszuführenden Befehl sowie verfügbare Parameter für den Befehl. Sie können auf andere Skriptdateien innerhalb der Artefaktdefinitionsdatei anhand ihres Namens verweisen.

Das folgende Beispiel zeigt die Abschnitte, die die grundlegende Struktur einer Definitionsdatei artifactfile.json bilden:

  {
    "$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": ""
    }
  }
Elementname Beschreibung
$schema Speicherort der JSON-Schemadatei Mithilfe der JSON-Schemadatei können Sie die Gültigkeit der Definitionsdatei testen.
title Der Name des Artefakts, der im Lab angezeigt werden soll. Erforderlich.
description Eine Beschreibung des Artefakts, die im Lab angezeigt werden soll. Erforderlich.
iconUri Der URI des Artefaktsymbols, das im Lab angezeigt werden soll.
targetOsType Das Betriebssystem der VM, auf der das Artefakt installiert werden soll. Unterstützte Werte: Windows, Linux. Erforderlich.
parameters Werte zum Anpassen des Artefakts bei der Installation auf der VM.
runCommand Der auf der VM auszuführende Befehl zur Installation des Artefakts. Erforderlich.

Artefaktparameter

Im Parameterabschnitt der Definitionsdatei geben Sie an, welche Werte ein Benutzer beim Installieren eines Artefakts eingeben kann. Auf diese Werte können Sie im Artefaktinstallationsbefehl verweisen.

Sie definieren Parameter mit der folgenden Struktur:

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }
Elementname Beschreibung
type Der Typ des Parameterwerts. Erforderlich.
displayName Name des Parameters, der dem Lab-Benutzer angezeigt werden soll. Erforderlich.
description Beschreibung des Parameters, die dem Lab-Benutzer angezeigt werden soll. Erforderlich.

Die zulässigen Parameterwerttypen sind:

Typ Beschreibung
string Eine beliebige gültige JSON-Zeichenfolge
int Eine beliebige gültige JSON-Ganzzahl
bool Eine beliebiger gültiger boolescher JSON-Wert
array Ein beliebiges gültiges JSON-Array

Geheimnisse als sichere Zeichenfolgen

Um Geheimnisse als sichere Zeichenfolgenparameter mit maskierten Zeichen in der Benutzeroberfläche zu deklarieren, verwenden Sie die folgende Syntax im Abschnitt parameters der Datei 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
    },

Der Artefakt-Installationsbefehl zur Ausführung des PowerShell-Skripts verwendet die sichere Zeichenfolge, die mit dem Befehl ConvertTo-SecureString erstellt wurde.

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

Protokollieren Sie keine Geheimnisse in der Konsole, da das Skript die Ausgabe für das Benutzerdebuggen erfasst.

Ausdrücke und Funktionen für Artefakte

Sie können zum Erstellen des Artefaktinstallationsbefehls Ausdrücke und Funktionen verwenden. Ausdrücke werten aus, wenn das Artefakt installiert wird. Ausdrücke können überall in einem JSON-Zeichenfolgenwert erscheinen und führen immer zu einem anderen JSON-Wert. Schließen Sie Ausdrücke in eckige Klammern ein: [ ]. Wenn Sie eine Literalzeichenfolge verwenden müssen, die mit einer Klammer beginnt, verwenden Sie zwei Klammern: [[.

In der Regel verwenden Sie Ausdrücke mit Funktionen, um einen Wert zu erstellen. Funktionsaufrufe werden als functionName(arg1, arg2, arg3) formatiert.

Zu den gängigen Funktionen gehören:

Funktion Beschreibung
parameters(parameterName) Gibt einen Parameterwert zurück, der beim Ausführen des Artefaktbefehls angegeben werden soll.
concat(arg1, arg2, arg3, ...) Kombiniert mehrere Zeichenfolgenwerte. Diese Funktion kann verschiedene Argumente verwenden.

Das folgende Beispiel verwendet Ausdrücke und Funktionen, um einen Wert zu erstellen:

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

Erstellen eines benutzerdefinierten Artefakts

So erstellen Sie ein benutzerdefiniertes Artefakt

  • Installieren Sie zum Arbeiten mit Artefaktdefinitionsdateien einen JSON-Editor. Visual Studio Code ist für Windows, macOS und Linux verfügbar.

  • Starten Sie mit der Beispieldefinitionsdatei artifactfile.json.

    Das öffentliche DevTest Labs-Artefaktrepository enthält eine umfangreiche Bibliothek mit Artefakten, die Sie verwenden können. Laden Sie eine Artefaktdefinitionsdatei herunter, und passen Sie sie an, um eigene Artefakte zu erstellen.

    Dieser Artikel verwendet die Definitionsdatei artifactfile.json und das PowerShell-Skript artifact.ps1 unter https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

  • Zeigen Sie mithilfe von IntelliSense gültige Elemente und Wertoptionen an, die zum Erstellen einer Artefaktdefinitionsdatei verwendet werden können. Beispielsweise zeigt IntelliSense beim Bearbeiten des targetOsType-Elements Windows- und Linux-Optionen an.

  • Speichern Sie Ihre Artefakte in öffentlichen oder privaten Git-Artefaktrepositorys.

    • Speichern Sie jede artifactfile.json-Artefaktdefinitionsdatei in einem separaten Verzeichnis, dessen Name mit dem Artefaktnamen identisch ist.
    • Speichern Sie die Skripts, auf die der Installationsbefehl verweist, im selben Verzeichnis wie die Artefaktdefinitionsdatei.

    Der folgende Screenshot zeigt ein Beispiel für einen Artefaktordner:

    Screenshot: Beispiel für einen Artefaktordner.

  • Um Ihre benutzerdefinierten Artefakte im öffentlichen DevTest Labs-Artefaktrepository zu speichern, öffnen Sie einen Pull Request für das Repository.

  • Informationen zum Hinzufügen Ihres privaten Artefaktrepositorys zu einem Lab finden Sie unter Hinzufügen eines Artefaktrepositorys zu Ihrem Lab in DevTest Labs.

Nächste Schritte