Come creare un file di configurazione WinGet

Per creare un file di configurazione WinGet:

1. Creare un file YAML seguendo la convenzione di denominazione dei file configurazione WinGet.
2. Acquisisci familiarità con il formato di un file di configurazione WinGet e collega lo schema del file corrente.
3. 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.
4. Identificare i moduli di PowerShell e le risorse DSC (Desired State Configuration) necessarie per eseguire le attività di configurazione desiderate.
5. Determinare le direttive e le impostazioni necessarie per ogni risorsa di configurazione.
6. Determinare le dipendenze per ogni risorsa.

Altre informazioni sull'uso del comando Configura WinGet.

Formato del file

Gestione pacchetti di 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 del formato del file di configurazione WinGet valido, è consigliabile usare Visual Studio Code con l'estensione YAML di RedHat per supportare la sintassi corretta, rilevare eventuali errori di formattazione, fornire supporto al passaggio del mouse e completamento automatico (quando collegato al file di schema JSON) e assicurarsi una formattazione valida.

Convenzione di denominazione dei file

La convenzione per la denominazione di un file di configurazione WinGet usa l'estensione di file ".winget" (ad esempio configuration.winget). Per i progetti basati su Git, la configurazione predefinita deve essere archiviata in una directory ".config" in: ./config/configuration.winget. In alcuni casi, più file di configurazione possono essere appropriati in base a toolchain o preferenze utente diverse. Questi file di configurazione aggiuntivi devono trovarsi anche nella directory ".config".

Sezioni di un file di configurazione WinGet

Un file di configurazione WinGet è separato in due sezioni principali:

1. Asserzioni: precondizioni necessarie per eseguire la configurazione.
2. Risorse: 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 per avere esito positivo nel computer che esegue il file. Le asserzioni possono essere completate in parallelo e non richiedono alcun ordine sequenziale.

Un'asserzione di esempio:

• versione del sistema operativo: versione minima del sistema operativo* installata sul computer. Man mano che le funzionalità vengono aggiunte nel tempo al sistema operativo, alcune vengono backportate per supportare le versioni precedenti e alcune non lo sono. È sempre utile verificare la disponibilità di una versione minima del sistema operativo per determinare se uno strumento o una funzionalità specifica può essere supportata necessaria per la configurazione. 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 appropriato 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, qualsiasi risorsa che identifica tale asserzione come dipendenza usando il dependsOn campo verrà ignorata e non verrà eseguita. In questo caso, anche se non sono state applicate modifiche di configurazione all'ambiente Windows, questa configurazione verrebbe considerata un risultato positivo.

Sezione Risorse

L'elenco delle risorse include 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 deve essere assegnato un nome, una descrizione della direttiva da eseguire e il modulo di PowerShell che sarà responsabile dell'esecuzione di tale direttiva, nonché di eventuali impostazioni o dipendenze associate.

File di configurazione WinGet di esempio

Ecco un esempio di file di configurazione WinGet formattato con configuration.winget:

# 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.Settings/WindowsSettings
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
        securityContext: elevated
      settings:
        DeveloperMode: true
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        securityContext: elevated
      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
        securityContext: elevated
      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:

1. Schema: la prima riga nel file di configurazione deve contenere il commento seguente: # 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 di schema più recente al momento di questo esempio è 0.2, quindi lo schema è stato immesso come : # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2.

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 assertions nodo e un resources nodo.

3. Asserzioni: elencare le precondizioni (o i prerequisiti) necessarie per questa configurazione in questa sezione.

4. Risorse: sia le sezioni assertions che resources di elenco sono costituite da singoli nodi resource per rappresentare l'attività di impostazione. Al modulo PowerShell dovrebbe essere assegnato un nome seguito dal nome della risorsa DSC del modulo, che verrà richiamata per applicare lo stato desiderato: resource. Ogni risorsa deve includere directives e settings. Facoltativamente, può includere anche un id valore. Quando si applica una configurazione, WinGet saprà installare il modulo dal di PowerShell Gallery e richiamare la risorsa DSC specificata .

5. Direttive: la directives sezione fornisce informazioni sul modulo e sulla risorsa. Questa sezione deve includere un description valore per descrivere l'attività di configurazione eseguita dal modulo. Il valore allowPrerelease consente di scegliere se la configurazione sarà consentita o meno (true) per usare i moduli "Versione preliminare" dal PowerShell Gallery. Alcune risorse DSC potrebbero dover essere eseguite con privilegi di amministratore. Il securityContext: elevated campo nella sezione direttive di una risorsa indica questo requisito. Se impostato su elevated, WinGet richiederà un'autorizzazione UAC all'inizio della configurazione. WinGet avvierà quindi due processi: uno che esegue risorse con privilegi elevati e un altro che esegue le risorse con i privilegi dell'utente corrente.

6. Impostazioni: il valore settings di una risorsa rappresenta la raccolta delle coppie nome-valore che vengono passate alla risorsa DSC di PowerShell. Le impostazioni possono rappresentare qualsiasi elemento dal fatto che la modalità sviluppatore sia abilitata, l'applicazione di una chiave reg o la definizione di una determinata impostazione di rete.

7. 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, questa risorsa fallirà automaticamente anch'essa.

8. ID: identificatore univoco per l'istanza di risorsa specifica. Il id valore può essere usato se un'altra risorsa ha una dipendenza da questa risorsa applicata per prima.

Organizzazione della sezione Risorse

Esistono diversi 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: organizzazione dell'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 dopo l'esecuzione del file: cosa viene installato per primo, secondo, quale impostazione viene aggiornata terza e così via.
• Possibilità di errore: organizzare l'elenco di risorse in base alla probabilità di un potenziale errore può aiutare gli utenti a intercettare i problemi nelle fasi iniziali del processo di configurazione e aiutarli a capire perché i passaggi rimanenti potrebbero non riuscire, consentendo loro di identificare e apportare le modifiche necessarie prima di investire molto tempo.
• Raggruppamento di tipi di risorse simili: l'organizzazione dell'elenco di risorse raggruppando tipi di risorse simili è un approccio comune nelle metodologie di progettazione software e può essere il più familiare per l'utente o per altri sviluppatori che usano il file di configurazione.

È consigliabile includere un file README.md con qualsiasi file di configurazione WinGet pubblicato Open Source, che includa l'approccio organizzativo della struttura dei file.

Uso della variabile ${WinGetConfigRoot}

Alcune risorse DSC possono accettare 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 winget configure comando e accodare il percorso relativo a tale file. Ciò è 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à utilizzando il ${WinGetConfigRoot} per puntare a un file .vsconfig nella directory radice di un progetto. Ciò significa 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 winget configure comando.

Dove trovare i moduli delle risorse DSC di PowerShell

Consulta l'elenco delle Risorse di Configurazione dello Stato Desiderato di PowerShell supportate da Microsoft, tra cui:

• Environment: Gestire una variabile di ambiente per una macchina o un processo.
• MsiPackage: installare o disinstallare un pacchetto MSI.
• del Registro di sistema: gestire una chiave o un valore del Registro di sistema.
• Script: Esegui blocchi di script di PowerShell.
• Servizio: 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 "Risorsa DSC" in "Categorie". Questo repository non viene verificato da Microsoft e contiene risorse provenienti da diversi autori e editori. I moduli di PowerShell devono sempre essere esaminati per verificarne la sicurezza e la credibilità prima di essere usati, poiché qualsiasi script arbitrario può essere incluso. Per altri suggerimenti sulla creazione di un file di configurazione WinGet attendibile, vedere How to check the trustworthiness of a WinGet Configuration file (Come controllare l'attendibilità di un file di configurazione WinGet ) per altri suggerimenti sulla creazione di un file di configurazione WinGet attendibile.