Dela via

Skapa anpassade artefakter för DevTest Labs

  • Artikel

Den här artikeln beskriver hur du skapar anpassade artefaktfiler för Azure DevTest Labs virtuella datorer (VM). DevTest Labs-artefakter anger åtgärder som ska utföras för att etablera en virtuell dator. En artefakt består av en artefaktdefinitionsfil och andra skriptfiler som du lagrar i en mapp på en Git-lagringsplats.

Artefaktdefinitionsfiler

Artefaktdefinitionsfiler är JSON-uttryck som anger vad du vill installera på en virtuell dator. Filerna definierar namnet på en artefakt, ett kommando som ska köras och tillgängliga parametrar för kommandot. Du kan referera till andra skriptfiler efter namn i artefaktdefinitionsfilen.

I följande exempel visas de avsnitt som utgör den grundläggande strukturen för en artefaktfile.json-artefaktdefinitionsfil :

  {
    "$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": ""
    }
  }
Elementnamn Beskrivning
$schema Plats för JSON-schemafilen. JSON-schemafilen kan hjälpa dig att testa giltigheten för definitionsfilen.
title Namnet på artefakten som ska visas i labbet. Krävs.
description Beskrivning av artefakten som ska visas i labbet. Krävs.
iconUri URI för artefaktikonen som ska visas i labbet.
targetOsType Operativsystem för den virtuella datorn som artefakten ska installeras på. Värden som stöds: Windows, Linux. Krävs.
parameters Värden för att anpassa artefakten vid installation på den virtuella datorn.
runCommand Kommandot för artefaktinstallation som ska köras på den virtuella datorn. Krävs.

Artefaktparametrar

I avsnittet parametrar i definitionsfilen anger du de värden som en användare kan ange när en artefakt installeras. Du kan referera till dessa värden i kommandot för artefaktinstallation.

Använd följande struktur för att definiera parametrar:

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }
Elementnamn Beskrivning
type Typ av parametervärde. Krävs.
displayName Namnet på parametern som ska visas för labbanvändaren. Krävs.
description Beskrivning av parametern som ska visas för labbanvändaren. Krävs.

De tillåtna parametervärdetyperna är:

Typ Beskrivning
string Valfri giltig JSON-sträng
int Ett giltigt JSON-heltal
bool Valfritt giltigt JSON-booleskt värde
array Alla giltiga JSON-matriser

Hemligheter som säkra strängar

Om du vill deklarera hemligheter som säkra strängparametrar med maskerade tecken i användargränssnittet använder du följande syntax i parameters avsnittet i filen 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
    },

Artefaktinstallationskommandot för att köra PowerShell-skriptet tar den säkra sträng som skapats med hjälp ConvertTo-SecureString av kommandot .

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

Logga inte hemligheter till konsolen eftersom skriptet samlar in utdata för användarfelsökning.

Artefaktuttryck och funktioner

Du kan använda uttryck och funktioner för att konstruera kommandot för artefaktinstallation. Uttryck utvärderas när artefakten installeras. Uttryck kan visas var som helst i ett JSON-strängvärde och returnera alltid ett annat JSON-värde. Omsluta uttryck med hakparenteser, [ ]. Om du behöver använda en literalsträng som börjar med en hakparentes använder du två hakparenteser [[.

Du använder vanligtvis uttryck med funktioner för att konstruera ett värde. Funktionsanrop formateras som functionName(arg1, arg2, arg3).

Vanliga funktioner är:

Funktion Beskrivning
parameters(parameterName) Returnerar ett parametervärde som ska anges när artefaktkommandot körs.
concat(arg1, arg2, arg3, ...) Kombinerar flera strängvärden. Den här funktionen kan ta olika argument.

I följande exempel används uttryck och funktioner för att konstruera ett värde:

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

Skapa en anpassad artefakt

Så här skapar du en anpassad artefakt:

  • Installera en JSON-redigerare för att arbeta med artefaktdefinitionsfiler. Visual Studio Code är tillgängligt för Windows, Linux och macOS.

  • Börja med en exempelartefaktfil.json-definitionsfil .

    Den offentliga DevTest Labs-artefaktlagringsplatsen har ett omfattande bibliotek med artefakter som du kan använda. Du kan ladda ned en artefaktdefinitionsfil och anpassa den för att skapa egna artefakter.

    Den här artikeln använder definitionsfilen artifactfile.json och artifact.ps1 PowerShell-skriptet på https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

  • Använd IntelliSense för att se giltiga element och värdealternativ som du kan använda för att skapa en artefaktdefinitionsfil. När du till exempel redigerar elementet targetOsType visar IntelliSense dig Windows eller Linux alternativ.

  • Lagra artefakterna i offentliga eller privata Git-artefaktlagringsplatser.

    • Lagra varje artefaktfil.json-artefaktdefinitionsfil i en separat katalog med samma namn som artefaktnamnet.
    • Lagra skripten som installationskommandot refererar till i samma katalog som artefaktdefinitionsfilen.

    Följande skärmbild visar en exempelartefaktmapp:

    Skärmbild som visar en exempelartefaktmapp.

  • Om du vill lagra dina anpassade artefakter i den offentliga DevTest Labs-artefaktlagringsplatsen öppnar du en pull-begäran mot lagringsplatsen.

  • Information om hur du lägger till din privata artefaktlagringsplats i ett labb finns i Lägga till en artefaktlagringsplats i ditt labb i DevTest Labs.

Nästa steg