Creare artefatti personalizzati per le macchine virtuali di DevTest Labs

Gli artefatti sono strumenti, azioni o software che è possibile aggiungere alle macchine virtuali di Azure DevTest Labs. Ad esempio, gli artefatti possono eseguire script, installare strumenti o eseguire azioni come l'aggiunta a un dominio. Gli utenti di DevTest Labs possono aggiungere elementi alle macchine virtuali e gli amministratori del lab possono specificare elementi obbligatori da aggiungere a tutte le macchine virtuali del lab.

Questo articolo descrive come creare artefatti per il provisioning di macchine virtuali di laboratorio. Un artefatto è costituito da un file JSON di definizione dell'artefatto e da altri file di script archiviati in una cartella del repository Git. È possibile archiviare gli artefatti in un repository Git privato o pubblico. Gli amministratori del lab possono aggiungere repository di artefatti ai lab in modo che tutti gli utenti del lab possano accedervi.

Prerequisiti

Per creare e usare i file di definizione degli artefatti, è necessario un editor JSON. Visual Studio Code è disponibile per Windows, Linux e macOS.
Per archiviare la definizione dell'artefatto e i file di script, è necessario un account GitHub.

Informazioni sui file di definizione degli artefatti

Un file di definizione dell'artefatto è costituito da un'espressione JSON che specifica l'azione da eseguire in una macchina virtuale. Il file definisce un nome di artefatto, un comando da eseguire e i parametri disponibili per il comando. Se l'artefatto contiene altri file di script, è possibile fare riferimento ai file in base al nome nel file di definizione dell'artefatto.

Nell'esempio seguente viene illustrata la struttura di base di un file di definizione dell'artefattoartifactfile.json .

  {
    "$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
    "title": "<title>",
    "description": "<description>",
    "iconUri": "",
    "targetOsType": "<os>",
    "parameters": {
      "<paramName>": {
        "type": "<type>",
        "displayName": "<display name>",
        "description": "<description>"
      }
    },
    "runCommand": {
      "commandToExecute": "<command>"
    }
  }

La definizione include gli elementi obbligatori e facoltativi seguenti:

Nome dell'elemento	Description
`$schema`	Percorso del file di schema JSON, che consente di testare la validità del file di definizione.
`title`	Nome dell'artefatto necessario da visualizzare.
`description`	Descrizione dell'artefatto obbligatorio.
`iconUri`	URI dell'icona dell'artefatto da mostrare.
`targetOsType`	Sistema operativo necessario per l'installazione. I valori supportati sono `Windows` o `Linux`.
`parameters`	Personalizzazioni degli artefatti disponibili durante l'installazione.
`runCommand`	Comando necessario per installare l'artefatto nella macchina virtuale.

Parametri dell'artefatto

La parameters sezione del file di definizione definisce le opzioni e i valori che gli utenti possono specificare quando installano l'artefatto. È possibile fare riferimento a questi parametri in runCommand.

La struttura seguente definisce un parametro:

  "parameters": {
    "<name>": {
      "type": "<type>",
      "displayName": "<display name>",
      "description": "<description>"
    }
  }

Ogni parametro richiede un nome e la definizione del parametro richiede gli elementi seguenti:

Nome dell'elemento	Description
`type`	Tipo di valore del parametro obbligatorio. Il tipo può essere qualsiasi json `string`valido, integer `int`, booleano `bool`o `array`.
`displayName`	Nome del parametro obbligatorio da visualizzare all'utente.
`description`	Descrizione del parametro obbligatoria.

Proteggere i parametri di stringa

Per includere segreti in una definizione di artefatto, dichiarare i segreti come stringhe sicure usando la secureStringParam sintassi nella parameters sezione del file di definizione. L'elemento description consente qualsiasi stringa di testo, inclusi gli spazi, e presenta la stringa nell'interfaccia utente come caratteri mascherati.


    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "<any text string>",
      "allowEmpty": false
    },

Di seguito runCommand viene usato uno script di PowerShell che accetta la stringa protetta creata usando il ConvertTo-SecureString comando . Lo script acquisisce l'output per il debug, quindi per la sicurezza non registrare l'output nella console.

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

Espressioni e funzioni degli artefatti

È possibile usare espressioni e funzioni per costruire il comando di installazione dell'artefatto. Le espressioni valutano quando viene installato l'artefatto.

Le espressioni possono essere visualizzate ovunque in un valore stringa JSON e restituiscono sempre un altro valore JSON. Racchiudere le espressioni tra parentesi angolari, [ ]. Se hai bisogno di utilizzare una stringa letterale che inizia con una parentesi quadra, utilizza 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	Description
`parameters(parameterName)`	Restituisce un valore di parametro da utilizzare quando viene eseguito il comando dell'artefatto.
`concat(arg1, arg2, arg3, ...)`	Combina più valori stringa e può accettare vari argomenti.

Nell'esempio seguente vengono utilizzate espressioni con la concat funzione per costruire un valore.

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

Creare un artefatto personalizzato

È possibile creare un artefatto personalizzato a partire da un file di definizione di esempioartifactfile.json . Il repository degli artefatti di DevTest Labs pubblico ha una libreria di artefatti. È possibile scaricare un file di definizione dell'artefatto e personalizzarlo per creare elementi personalizzati.

Scaricare il file di definizione artifactfile.json e artifact.ps1 script di PowerShell da https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.
Modificare il file di definizione dell'artefatto per apportare alcune modifiche valide a elementi e valori. In Visual Studio Code è possibile usare IntelliSense per visualizzare gli elementi e le opzioni di valore validi. Ad esempio, quando si modifica l'elemento targetOsType , IntelliSense mostra le Windows opzioni o Linux .
Archiviare l'artefatto in un repository di artefatti Git pubblico o privato.
- Archivia ogni file di definizione dell'artefatto artifactfile.json in una directory separata con lo stesso 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:

Annotazioni

Per aggiungere gli artefatti personalizzati al repository di artefatti DevTest Labs pubblico, aprire una pull request sul repository.

Passaggi successivi

Valutazione

Questa pagina ti è stata utile?

Last updated on 2025-12-16