Skapa anpassade artefakter för DevTest Labs

Artikel
09/30/2023

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.

Information om hur du lägger till dina artefaktlagringsplatser i labb finns i Lägga till en artefaktlagringsplats i labbet.
Information om hur du lägger till artefakter som du skapar i virtuella datorer finns i Lägga till artefakter i virtuella DevTest Labs-datorer.
Information om hur du anger obligatoriska artefakter som ska läggas till i alla virtuella labbdatorer finns i Ange obligatoriska artefakter för virtuella DevTest Labs-datorer.

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:
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.