Creare artefatti personalizzati per DevTest Labs

Articolo
09/30/2023

Questo articolo descrive come creare file di artefatti personalizzati per le macchine virtuali di Azure DevTest Labs. Gli artefatti di DevTest Labs specificano azioni da eseguire per effettuare il provisioning di una macchina virtuale. Un artefatto è costituito da un file di definizione dell'artefatto e altri file di script archiviati in una cartella in un repository Git.

Per informazioni sull'aggiunta dei repository di artefatti ai lab, vedere Aggiungere un repository di artefatti al lab.
Per informazioni sull'aggiunta degli artefatti creati alle macchine virtuali, vedere Aggiungere elementi alle macchine virtuali DevTest Labs.
Per informazioni sulla specifica degli artefatti obbligatori da aggiungere a tutte le macchine virtuali del lab, vedere Specificare gli artefatti obbligatori per le macchine virtuali DevTest Labs.

File di definizione degli artefatti

I file di definizione degli artefatti sono espressioni JSON che specificano cosa si vuole installare in una macchina virtuale. I file definiscono il nome di un artefatto, un comando da eseguire e i parametri disponibili per il comando. È possibile fare riferimento ad altri file di script in base al nome nel file di definizione dell'artefatto.

Nell'esempio seguente vengono illustrate le sezioni che costituiscono la struttura di base di un file di definizione dell'artefatto 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": ""
    }
  }

Nome dell'elemento	Descrizione
`$schema`	Posizione del file di schema JSON. Il file di schema JSON aiuta a testare la validità del file di definizione.
`title`	Nome dell'artefatto da visualizzare nel lab. Obbligatoria.
`description`	Descrizione dell'artefatto da visualizzare nel lab. Obbligatoria.
`iconUri`	URI dell'icona dell'artefatto da visualizzare nel lab.
`targetOsType`	Sistema operativo della macchina virtuale in cui installare l'artefatto. Valori supportati: `Windows`, `Linux`. Obbligatoria.
`parameters`	Valori per personalizzare l'artefatto durante l'installazione nella macchina virtuale.
`runCommand`	Comando di installazione dell'artefatto da eseguire nella macchina virtuale. Obbligatoria.

Parametri dell'elemento

Nella sezione parametri del file di definizione specificare i valori che un utente può inserire durante l'installazione di un artefatto. È possibile fare riferimento a questi valori nel comando di installazione dell'elemento.

Per definire i parametri, usare la struttura seguente:

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }

Nome dell'elemento	Descrizione
`type`	Tipo di valore del parametro. Obbligatoria.
`displayName`	Nome del parametro da visualizzare all'utente del lab. Obbligatoria.
`description`	Descrizione del parametro da visualizzare all'utente del lab. Obbligatoria.

I tipi di valore dei parametri consentiti sono:

Tipo	Descrizione
`string`	Qualsiasi stringa JSON valida
`int`	Qualsiasi intero JSON valido
`bool`	Qualsiasi booleano JSON valido
`array`	Qualsiasi matrice JSON valida

Segreti come stringhe sicure

Per dichiarare i segreti come parametri stringa sicuri con caratteri mascherati nell'interfaccia utente, usare la sintassi seguente nella parameters sezione del 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
    },

Il comando di installazione dell'artefatto per eseguire lo script di PowerShell accetta la stringa sicura creata usando il ConvertTo-SecureString comando .

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

Non registrare i segreti nella console, perché lo script acquisisce l'output per il debug utente.

Espressioni e funzioni dell’elemento

È possibile usare espressioni e funzioni per costruire il comando di installazione dell'elemento. Le espressioni valutano quando l'artefatto viene installato. Le espressioni possono essere visualizzate ovunque in un valore stringa JSON e restituiscono sempre un altro valore JSON. Racchiudere espressioni con parentesi quadre, [ ]. Se è necessario usare una stringa letterale che inizia con una parentesi quadre, usare due parentesi quadre [[.

In genere si usano espressioni con funzioni per costruire un valore. Le chiamate di funzione vengono formattate come functionName(arg1, arg2, arg3).

Le funzioni comuni includono:

Funzione	Descrizione
`parameters(parameterName)`	Restituisce un valore di parametro da specificare quando viene eseguito il comando dell'artefatto.
`concat(arg1, arg2, arg3, ...)`	combina più valori stringa. Questa funzione può accettare vari argomenti.

Nell'esempio seguente vengono usate espressioni e funzioni per costruire un valore:

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

Creare un elemento personalizzato

Per creare un artefatto personalizzato:

Installare un editor JSON per usare i file di definizione degli artefatti. Visual Studio Code è disponibile per Windows, Linux e macOS.
Iniziare con un file di definizione di sample artifactfile.json .

Il repository degli artefatti di DevTest Labs pubblico include una libreria completa di artefatti che è possibile usare. È possibile scaricare un file di definizione dell'artefatto e personalizzarlo per creare elementi personalizzati.

Questo articolo usa il file di definizione artifactfile.json e artifact.ps1 script di PowerShell in https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.
Usare IntelliSense per visualizzare gli elementi e le opzioni di valore validi che è possibile usare per costruire un file di definizione dell'artefatto. Ad esempio, quando si modifica l'elemento, IntelliSense mostra le opzioni o Linux l'utente.targetOsTypeWindows
Archiviare gli artefatti in repository di artefatti Git pubblici o privati.
- Archiviare ogni file di definizione dell'artefatto artifactfile.json in una directory separata denominata uguale al nome dell'artefatto.
- Archiviare gli script a cui fa riferimento il comando di installazione nella stessa directory del file di definizione dell'artefatto.
Lo screenshot seguente mostra una cartella di artefatti di esempio:
Per archiviare gli artefatti personalizzati nel repository dell'artefatto DevTest Labs pubblico, aprire una richiesta pull rispetto al repository.
Per aggiungere il repository di artefatti privati a un lab, vedere Aggiungere un repository di artefatti al lab in DevTest Labs.