Condividi tramite

Creare artefatti personalizzati per DevTest Labs

  • Articolo

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.

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:

    Screenshot che mostra una cartella dell'artefatto 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.

Passaggi successivi