Scrivere un file di personalizzazione per una casella di sviluppo

Questo articolo illustra come creare e testare un file di personalizzazione per la casella di sviluppo usando Visual Studio Code (VS Code) e Dev Home.

Esistono due modi per usare un file di personalizzazione in Microsoft Dev Box. Le personalizzazioni del team vengono applicate automaticamente quando gli sviluppatori li configurano in un pool. Le singole personalizzazioni vengono applicate quando un utente crea una casella di sviluppo.

Questo articolo illustra come definire nuove attività nel file di personalizzazione, applicarle alle finestre di sviluppo e testare queste personalizzazioni direttamente in VS Code.

Prerequisiti

Per seguire la procedura descritta in questo articolo, è necessario:

• Avere configurato un dev center con una definizione di dev box, un pool di dev box e un progetto dev box in modo da poter creare una casella di sviluppo.
• Essere membri del gruppo di sicurezza Dev Box Users per almeno un progetto.
• Avere un catalogo collegato al dev center con attività che è possibile usare nel file di personalizzazione. Se non si ha un catalogo, vedere Aggiungere e configurare un catalogo da GitHub o Azure Repos.

Autorizzazioni necessarie per configurare le personalizzazioni

Per eseguire le azioni necessarie per la creazione e l'applicazione di personalizzazioni a una finestra di sviluppo, sono necessarie le autorizzazioni seguenti:

Che cos'è un file di personalizzazione?

Le personalizzazioni di Dev Box usano un file in formato YAML per specificare un elenco di attività da applicare quando uno sviluppatore crea una casella di sviluppo. Queste attività possono essere semplici come l'installazione di un pacchetto o l'esecuzione di un set complesso di script per configurare una codebase. Le attività identificano il catalogo e forniscono parametri come il nome del software da installare. Il file di personalizzazione viene quindi reso disponibile agli sviluppatori che creano finestre di sviluppo.

L'esempio seguente usa un'attività winget per installare VS Code e un'attività git-clone per clonare un repository:

# From https://github.com/microsoft/devcenter-examples
$schema: 1.0
tasks:
  - name: winget
    parameters:
      package: Microsoft.VisualStudioCode
      runAsUser: true
  - name: git-clone
    description: Clone this repository into C:\Workspaces
    parameters:
      repositoryUrl: https://github.com/OrchardCMS/OrchardCore.git
      directory: C:\Workspaces

Esistono due modi per usare un file di personalizzazione: le singole personalizzazioni si applicano a una singola casella di sviluppo e le personalizzazioni del team si applicano a un intero team.

Singoli file di personalizzazione

• Contiene attività applicate quando uno sviluppatore crea una casella di sviluppo.
• Vengono caricati dallo sviluppatore durante la creazione di una casella di sviluppo.

File di personalizzazione del team

• Contiene attività applicate quando uno sviluppatore crea una casella di sviluppo.
• Vengono condivisi tra un team o un progetto.
• Includere un campo che specifica l'immagine di base.
• Sono denominati imagedefinition.yaml.
• Vengono caricati nel repository che ospita un catalogo.
• Vengono usati automaticamente quando uno sviluppatore crea una casella di sviluppo da un pool configurato.

az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"

Creare un file di personalizzazione

È possibile creare e gestire i file di personalizzazione usando VS Code. È possibile usare l'estensione Microsoft Dev Box in VS Code per individuare le attività nel catalogo collegato e testare il file di personalizzazione.

1. Creare una casella di sviluppo (o usare una casella di sviluppo esistente) per il test.

2. Nella casella di sviluppo di test installare VS Code e quindi installare l'estensione Dev Box.

3. Scaricare un file di personalizzazione YAML di esempio dal repository degli esempi e aprirlo in VS Code.

4. Individuare le attività disponibili nel catalogo usando il riquadro comandi. Selezionare Visualizza>riquadro comandi Casella>di sviluppo: elencare le attività disponibili per questa casella di sviluppo.

   

5. Testare la personalizzazione in VS Code usando il riquadro comandi. Selezionare Visualizza>riquadro comandi Casella>di sviluppo: Applica attività di personalizzazione.

   

6. Il file di personalizzazione viene eseguito immediatamente e applica le attività specificate alla casella di sviluppo di test. Esaminare le modifiche e controllare il terminale di VS Code per eventuali errori o avvisi generati durante l'esecuzione dell'attività.

7. Quando il file di personalizzazione viene eseguito correttamente, caricarlo nel catalogo.

Clonare un repository privato usando un file di personalizzazione

È possibile usare i segreti dell'insieme di credenziali delle chiavi di Azure nelle personalizzazioni YAML per clonare repository privati o con qualsiasi attività personalizzata creata che richiede un token di accesso. In un file di personalizzazione del team è possibile usare un token di accesso personale archiviato in un insieme di credenziali delle chiavi per accedere a un repository privato.

Usare i segreti dell'insieme di credenziali delle chiavi nei file di personalizzazione del team

Per clonare un repository privato, archiviare il token di accesso personale come segreto dell'insieme di credenziali delle chiavi e usarlo quando si richiama l'attività git-clone nella personalizzazione.

Per configurare i segreti dell'insieme di credenziali delle chiavi da usare nelle personalizzazioni YAML:

1. Assicurarsi che l'identità gestita del progetto dev center abbia il ruolo Lettore dell'insieme di credenziali delle chiavi e il ruolo Utente dei segreti dell'insieme di credenziali delle chiavi nell'insieme di credenziali delle chiavi.
2. Concedere il ruolo utente dei segreti dell'insieme di credenziali delle chiavi per il segreto dell'insieme di credenziali delle chiavi a ogni utente o gruppo di utenti in grado di utilizzare il segreto durante la personalizzazione di una casella di sviluppo. L'utente o il gruppo a cui viene concesso il ruolo deve includere l'identità gestita per il dev center, il proprio account utente e qualsiasi utente o gruppo che necessita del segreto durante la personalizzazione di una casella di sviluppo.

Per altre informazioni, vedi:

• Configurare un'identità gestita per un dev center
• Concedere all'identità gestita l'accesso al segreto dell'insieme di credenziali delle chiavi

È possibile fare riferimento al segreto nella personalizzazione YAML nel formato seguente, che usa l'attività git-clone come esempio:

$schema: "1.0"
tasks:
   name: git-clone
   description: Clone this repository into C:\Workspaces
      parameters:
         repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
         directory: C:\Workspaces
         pat: '{{KEY_VAULT_SECRET_URI}}'

Usare i segreti dell'insieme di credenziali delle chiavi nei singoli file di personalizzazione

Se si vuole clonare un repository Azure Repos privato da un singolo file di personalizzazione, non è necessario configurare un segreto in Azure Key Vault. È invece possibile usare {{ado}} o {{ado://your-ado-organization-name}} come parametro. Questo parametro recupera un token di accesso per conto dell'utente durante la creazione di una casella di sviluppo. Il token di accesso dispone dell'autorizzazione di sola lettura per il repository.

L'attività git-clone nel catalogo di avvio rapido usa il token di accesso per clonare il repository. Ecco un esempio:

tasks:
   name: git-clone
   description: Clone this repository into C:\Workspaces
      parameters:
         repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
         directory: C:\Workspaces
         pat: '{{ado://YOUR_ADO_ORG}}'

Il dev center deve accedere all'insieme di credenziali delle chiavi. I centri di sviluppo non supportano i tag di servizio, quindi se l'insieme di credenziali delle chiavi viene mantenuto privato, è necessario consentire ai servizi Microsoft attendibili di ignorare il firewall.

Per informazioni su come consentire ai servizi Microsoft attendibili di ignorare il firewall, vedere Configurare le impostazioni di rete di Azure Key Vault.

Personalizzare la casella di sviluppo usando i file di configurazione WinGet esistenti

La configurazione winGet adotta un approccio config-as-code per definire i set univoci di impostazioni software e di configurazione necessarie per ottenere l'ambiente Windows in uno stato pronto al codice. È anche possibile usare questi file di configurazione per configurare una finestra di sviluppo usando un'attività WinGet inclusa nel catalogo di avvio rapido fornito da Microsoft.

L'esempio seguente mostra un file di personalizzazione della finestra di sviluppo che chiama un file DSC (Desired State Configuration) WinGet esistente:

tasks:
    - name: winget
      parameters:
          configure: "projectConfiguration.dsc.yaml"

Per altre informazioni, vedere Configurazione di WinGet.

Condividere un file di personalizzazione da un repository di codice

Rendere il file di personalizzazione disponibile per i pool di dev box denominandolo imagedefinition.yaml e caricandolo nel repository che ospita il catalogo. Quando si crea un pool di box di sviluppo, è possibile selezionare il file di personalizzazione dal catalogo da applicare alle caselle di sviluppo nel pool.

Contenuto correlato

• Personalizzazioni del team di Microsoft Dev Box
• Configurare l'immagine per le personalizzazioni del team di Dev Box
• Aggiungere e configurare un catalogo da GitHub o Azure Repos