Come creare un file di configurazione WinGet

Articolo
01/10/2024

Per creare un file di configurazione WinGet:

Creare un file YAML seguendo la convenzione di denominazione dei file per la configurazione WinGet.
Acquisire familiarità con il formato di un file di configurazione WinGet e collegare lo schema file corrente.
Determinare l'elenco di Asserzioni (precondizioni necessarie) e Risorse (l'elenco delle installazioni e delle configurazioni necessarie per ottenere l'ambiente di sviluppo del computer allo stato desiderato) da includere nel file.
Identificare i moduli di PowerShell e le risorse DSC (Desired State Configuration) necessarie per eseguire le attività di configurazione desiderate.
Determinare le direttive e le impostazioni necessarie per ogni risorsa di configurazione.
Determinare le dipendenze per ogni risorsa.

Altre informazioni sull'uso del comando Configura WinGet.

File format

Gestione pacchetti Windows usa manifesti (file YAML) per individuare e installare pacchetti per gli utenti di Windows. I file di configurazione WinGet usano lo stesso formato di stile YAML, aggiungendo una specifica dello schema JSON per definire la struttura e la convalida del file. Per facilitare ulteriormente il rilevamento della validità del formato del file di configurazione WinGet, è consigliabile usare Visual Studio Code con l'estensione YAML di RedHat per supportare la sintassi corretta, rilevare eventuali errori di formattazione, fornire supporto per l'attivazione al passaggio del mouse e il completamento automatico (quando collegato al file di schema JSON) e assicurarsi che la formattazione sia valida.

Convenzione di denominazione dei file

La convenzione per la denominazione di un file di configurazione WinGet è configuration.dsc.yaml. Per i progetti basati su Git, la configurazione predefinita deve essere archiviata in una directory "configurations" in: ./configurations/configuration.dsc.yaml.

Sezioni di un file di configurazione WinGet

Un file di configurazione WinGet contiene due sezioni principali distinte:

Asserzioni: le precondizioni necessarie per eseguire la configurazione.
Risorse: l'elenco di software e strumenti da installare, le impostazioni di configurazione per tali installazioni e le impostazioni di configurazione per il sistema operativo Windows.

Sezione Asserzioni

L'elenco delle asserzioni copre le precondizioni (o i prerequisiti) necessarie per le risorse elencate in questo file di configurazione WinGet perché l'esecuzione del file nel computer abbia esito positivo. Le asserzioni possono essere completate in parallelo e non richiedono un ordine sequenziale.

Un'asserzione di esempio:

Versione del sistema operativo: versione minima del sistema operativo* installata nel computer. Man mano che nel tempo vengono aggiunte funzionalità al sistema operativo, solo alcune vengono sottoposte a backporting per supportare le versioni precedenti. È sempre utile verificare se uno strumento o una funzionalità specifica necessaria per la configurazione richiede una versione minima del sistema operativo. Ad esempio, WinGet (Gestione pacchetti Windows) richiede almeno Windows 10, versione 1809 o successiva. Tutte le versioni precedenti di Windows non supportano WinGet. *È possibile che le risorse DSC di PowerShell modifichino lo stato del sistema, ma non sarebbe opportuno chiamare Windows Update e modificare la versione del sistema operativo nella configurazione del progetto per un progetto open source.

Se un'asserzione restituisce "false" per indicare che il sistema non è nello stato desiderato, qualunque risorsa che identifica tale asserzione come dipendenza usando il campo dependsOn verrà ignorata e non verrà eseguita. In questo caso, anche se all'ambiente Windows se non sono state applicate modifiche di configurazione, questa configurazione verrebbe considerata un risultato positivo.

Sezione risorse

L'elenco delle risorse comprende tutti i software, gli strumenti, i pacchetti e così via che devono essere installati e le impostazioni di configurazione per il sistema operativo Windows o le applicazioni installate. A ogni risorsa dovrà essere assegnato un nome, una descrizione della direttiva da eseguire e il modulo di PowerShell che sarà responsabile dell'esecuzione di tale direttiva, nonché eventuali impostazioni o dipendenze associate.

File di configurazione WinGet di esempio

Di seguito è riportato un esempio di file di configurazione WinGet configuration.dsc.yaml formattato:

# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
properties:
  assertions:
    - resource: Microsoft.Windows.Developer/OsVersion
      directives:
        description: Verify min OS version requirement
        allowPrerelease: true
      settings:
        MinVersion: '10.0.22000'
  resources:
    - resource: Microsoft.Windows.Developer/DeveloperMode
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
      settings:
        Ensure: Present
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        allowPrerelease: true
      settings:
        id: Microsoft.VisualStudio.2022.Community
        source: winget
    - resource: Microsoft.VisualStudio.DSC/VSComponents
      dependsOn:
        - vsPackage
      directives:
        description: Install required VS workloads from vsconfig file
        allowPrerelease: true
      settings:
        productId: Microsoft.VisualStudio.Product.Community
        channelId: VisualStudio.17.Release
        vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
        includeRecommended: true
  configurationVersion: 0.2.0

I componenti di questo file sono costituiti da:

Schema: la prima riga nel file di configurazione deve contenere il commento # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #> per stabilire lo schema DSC seguito dal file. Per trovare la versione più recente dello schema di configurazione WinGet, passare a https://aka.ms/configuration-dsc-schema/. Il numero dello schema più recente al momento della stesura di questo esempio è 0.2, quindi lo schema è stato immesso come: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2.
Proprietà: il nodo radice per un file di configurazione è properties che deve contenere una versione di configurazione (configurationVersion: 0.2.0 in questo esempio). Questa versione deve essere aggiornata in base agli aggiornamenti del file di configurazione. Il nodo delle proprietà deve contenere un nodo assertions e un nodo resources.
Asserzioni: elencare le precondizioni (o i prerequisiti) necessarie per questa configurazione in questa sezione.
Risorse: entrambe assertions le sezioni e resources le sezioni dell'elenco sono costituite da singoli resource nodi per rappresentare l'attività di configurazione. All'elemento resource deve essere assegnato il nome del modulo PowerShell seguito dal nome della risorsa DSC del modulo che verrà richiamata per applicare lo stato desiderato: {ModuleName}/{DscResource}. Ogni risorsa deve includere directives e settings. Facoltativamente, può includere anche un valore id. Quando si applica una configurazione, WinGet saprà installare il modulo da PowerShell Gallery e richiamare la risorsa DSC specificata.
Direttive: la sezione directives fornisce informazioni sul modulo e la risorsa. Questa sezione deve includere un valore description per descrivere l'attività di configurazione eseguita dal modulo. Il valore allowPrerelease consente di scegliere se alla configurazione sarà consentito (true) usare i moduli in versione preliminare (prerelease) da PowerShell Gallery.
Impostazioni: il valore settings di una risorsa rappresenta la raccolta di coppie nome-valore passate alla risorsa DSC di PowerShell. Le impostazioni possono rappresentare qualsiasi cosa, dall'abilitazione o meno della modalità sviluppatore all'applicazione di una chiave del Registro di sistema o alla definizione di una determinata impostazione di rete.
Dipendenze: il valore dependsOn di una risorsa determina se è necessario completare qualsiasi altra asserzione o risorsa prima di iniziare questa attività. Se la dipendenza non è riuscita, anche questa risorsa avrà automaticamente esito negativo.
ID: identificatore univoco per l'istanza della risorsa specifica. Il valore id può essere utilizzato se un'altra risorsa ha una dipendenza da questa risorsa applicata per prima.

Organizzazione della sezione Risorse

Esistono vari approcci da considerare quando si determina come organizzare la sezione Risorse del file di configurazione WinGet. È possibile organizzare l'elenco dei file in base a:

Ordine di esecuzione: organizzare l'elenco di risorse in base all'ordine logico in cui devono essere eseguite. Questo approccio può aiutare l'utente a comprendere e seguire i passaggi di automazione eseguiti al momento dell'esecuzione del file, ossia cosa viene installato per primo e per secondo, quale impostazione viene aggiornata al terzo passaggio e così via.
Possibilità di errore: organizzare l'elenco di risorse in base alla probabilità di un potenziale errore può aiutare gli utenti a rilevare precocemente i problemi nel processo di configurazione e a capire perché i passaggi rimanenti potrebbero non riuscire, consentendo loro di identificare e apportare le modifiche necessarie senza perdere troppo tempo.
Raggruppamento di tipi di risorse simili: organizzare l'elenco di risorse raggruppando tipi di risorse simili è un approccio comune nelle metodologie di progettazione del software e può essere il più familiare per chi crea il file di configurazione o per gli altri sviluppatori che lo useranno.

È consigliabile includere un file README.md con qualsiasi file di configurazione WinGet open source pubblicato, che includa l'approccio adottato per organizzare la struttura del file.

Uso della variabile ${WinGetConfigRoot}

Alcune risorse DSC possono accettare in un parametro che specifica il percorso di un file. Anziché specificare il percorso completo, è possibile usare la variabile ${WinGetConfigRoot} per definire la directory di lavoro in cui viene eseguito il comando winget configure e aggiungere il percorso relativo a tale file. Questo è utile per generalizzare un file di configurazione in modo che sia indipendente dal computer. La risorsa Microsoft.VisualStudio.DSC/VSComponents nell'esempio precedente illustra questa funzionalità usando ${WinGetConfigRoot} per puntare a un file con estensione vsconfig nella directory radice di un progetto. Questo vuol dire anche che l'utente deve assicurarsi che il file di destinazione esista nel percorso relativo in base alla directory di lavoro corrente prima di eseguire il comando winget configure.

Dove trovare i moduli delle risorse DSC di PowerShell

Vedere l'elenco delle risorse PowerShell Desired State Configuration pronte all'uso supportate da Microsoft, tra cui:

Environment: gestire una variabile di ambiente per un computer o un processo.
MsiPackage: installare o disinstallare un pacchetto MSI.
Registry: gestire una chiave o un valore del Registro di sistema.
Script: eseguire blocchi di script di PowerShell.
Service: gestire un servizio Windows.
WindowsFeature: installare o disinstallare un ruolo o una funzionalità di Windows.
WindowsProcess: avviare o arrestare un processo di Windows.

È anche possibile trovare i moduli delle risorse DSC di PowerShell in PowerShell Gallery. Questa raccolta ospita centinaia di moduli di PowerShell contenenti risorse DSC (Desired State Configuration) inviate dalla community degli utenti. È possibile filtrare i risultati della ricerca applicando il filtro "DSC Resource" in "Categories". Questo repository non è verificato da Microsoft e contiene risorse provenienti da diversi autori e editori. I moduli di PowerShell devono essere sempre esaminati prima dell'uso per verificarne la sicurezza e la credibilità, visto che potrebbe essere incluso qualunque script arbitrario. Vedere Come controllare l'attendibilità di un file di configurazione WinGet per altri suggerimenti sulla creazione di un file di configurazione WinGet attendibile.

Condividi tramite