Linee guida e procedure consigliate per la pubblicazione in PowerShell Gallery

  • Articolo

Questo articolo descrive le procedure consigliate usate dai team Microsoft per garantire che i pacchetti pubblicati in PowerShell Gallery vengano adottati in modo estensivo e offrano valore aggiunto agli utenti. Le procedure consigliate si basano sulle modalità di gestione dei dati del manifesto in PowerShell Gallery e sui commenti e suggerimenti di numerosi utenti di PowerShell Gallery. I pacchetti pubblicati attenendosi a queste linee guida hanno maggiori probabilità di essere installati e considerati attendibili e attraggono un numero maggiore di utenti.

Di seguito sono elencate le linee guida che definiscono un pacchetto di PowerShell Gallery di qualità, le impostazioni facoltative più importanti di un manifesto e suggerimenti per migliorare il codice con i commenti e i suggerimenti dei revisori iniziali e con Powershell Script Analyzer. Sono incluse anche linee guida per creare versioni del modulo, documentazione, test ed esempi per l'uso degli elementi condivisi. Questa documentazione segue in gran parte le linee guida per la pubblicazione di moduli risorsa DSC di qualità.

Per informazioni sulle modalità di pubblicazione di un pacchetto in PowerShell Gallery vedere Creazione e pubblicazione di un pacchetto.

Sono graditi i commenti e i suggerimenti relativi a queste linee guida. Per pubblicare osservazioni è possibile aprire un caso nell'archivio della documentazione GitHub.

Procedure consigliate per la pubblicazione di pacchetti

Le seguenti procedure consigliate sono state segnalate come importanti dagli utenti degli elementi di PowerShell Gallery e sono elencate in ordine di priorità nominale. I pacchetti creati usando queste linee guida hanno molte più probabilità di essere scaricati e adottati da altri utenti.

  • Usare PSScriptAnalyzer
  • Includere documentazione ed esempi
  • Rispondere a commenti e suggerimenti
  • Includere moduli anziché script
  • Includere un collegamento a un sito di progetto
  • Contrassegnare il pacchetto con PSEdition(s) e le piattaforme compatibili
  • Includere test con i moduli
  • Includere e/o collegare condizioni di licenza
  • Firmare il codice
  • Osservare le linee guida SemVer per il controllo delle versioni
  • Usare tag comuni, documentati nei tag comuni di PowerShell Gallery
  • Pubblicazione di test usando un repository locale
  • Usare PowerShellGet per la pubblicazione

Ogni voce viene descritta brevemente nelle sezioni che seguono.

Usare PSScriptAnalyzer

PSScriptAnalyzer è uno strumento di analisi del codice statico gratuito che funziona con il codice PowerShell. PSScriptAnalyzer identifica i problemi più comuni del codice di PowerShell e in molti casi offre un suggerimento per la risoluzione. Lo strumento è facile da usare e classifica i problemi come Error (Errore, problema grave che deve essere risolto), Warning (Avviso, problema che va esaminato e dovrebbe essere risolto) e Information (Informazione, problema da esaminare per la conformità alle procedure consigliate). Tutti i pacchetti pubblicati in PowerShell Gallery vengono esaminati con PSScriptAnalyzer e gli eventuali errori vengono restituiti al proprietario e devono essere risolti.

La procedura consigliata consiste nell'eseguire Invoke-ScriptAnalyzer con -Recurse e -Severity impostata su Warning (Avviso).

Esaminare i risultati e verificare quanto segue:

  • Tutti i problemi di tipo Error sono stati corretti o sono illustrati nella documentazione.
  • Tutti i problemi di tipo Warning sono stati esaminati e risolti se necessario.

Per gli utenti che scaricano pacchetti da PowerShell Gallery è vivamente consigliata l'esecuzione di PSScriptAnalyzer e l'esame di tutti i problemi di tipo Error e Warning. Se un utente nota che PSScriptAnalyzer segnala un errore, probabilmente tenterà di contattare il proprietario del pacchetto corrispondente. Se esiste un motivo fondato per mantenere nel pacchetto codice che viene segnalato come errore, aggiungere le informazioni corrispondenti alla documentazione, per evitare di dover rispondere molte volte alla stessa domanda.

Includere documentazione ed esempi

La documentazione e gli esempi sono il metodo migliore per consentire agli utenti di trarre il massimo vantaggio dal codice condiviso.

La documentazione è l'elemento più importante da includere nei pacchetti pubblicati in PowerShell Gallery. In genere gli utenti ignorano i pacchetti privi di documentazione, perché dovrebbero leggere direttamente il codice per capire che cos'è il pacchetto e come va usato. Sono disponibili vari articoli che illustrano come includere documentazione con i pacchetti di PowerShell, tra cui:

  • Suggerimenti per la creazione della documentazione sono disponibili in How to Write Cmdlet Help (Come scrivere documentazione per i cmdlet).
  • La creazione di documentazione per i cmdlet è l'approccio migliore per script, funzioni o cmdlet di PowerShell. Per informazioni su come creare la Guida per i cmdlet, iniziare da How to Write Cmdlet Help (Come scrivere la Guida per i cmdlet). Per aggiungere elementi di documentazione in uno script vedere About Comment Based Help (Informazioni sulla documentazione basata sui commenti).
  • Molti moduli includono anche documentazione in formato testo, ad esempio file Markdown. Questa soluzione può essere utile se è disponibile un sito del progetto in GitHub, dove Markdown è un formato molto usato. La procedura consigliata è l'uso di Markdown per GitHub.

Gli esempi indicano agli utenti come usare il pacchetto. Secondo molti sviluppatori, per capire come usare un elemento è utile vedere gli esempi prima della documentazione. I migliori esempi indicano il funzionamento di base e un caso d'uso simulato realistico e includono commenti dettagliati al codice. Gli esempi per i moduli pubblicati in PowerShell Gallery dovrebbero essere inclusi in una cartella Examples sotto la cartella radice del modulo.

Un modello ottimale per gli esempi è disponibile nel modulo PSDscResource nella cartella Examples\RegistryResource. All'inizio di ogni file sono presenti quattro casi d'uso di esempio, corredati da una breve descrizione.

Gestire le dipendenze

È importante specificare i moduli da cui dipende il modulo nel manifesto del modulo. In questo modo l'utente finale non deve preoccuparsi di installare le versioni appropriate dei moduli da cui dipende il proprio modulo. Per specificare i moduli dipendenti è necessario usare il campo modulo obbligatorio nel manifesto del modulo. Prima di importare il modulo verranno così caricati tutti i moduli elencati nell'ambiente globale, a meno che non siano già stati caricati. Ad esempio alcuni moduli potrebbero essere già stati caricati da un modulo diverso. È anche possibile indicare una versione specifica da caricare usando il campo RequiredVersion invece del campo ModuleVersion. Quando si usa ModuleVersion viene caricata la versione più recente disponibile, comunque non inferiore alla versione specificata. Quando non si usa il campo RequiredVersion per indicare una versione specifica, è importante monitorare gli aggiornamenti delle versioni per il modulo obbligatorio. È di fondamentale importanza essere a conoscenza di eventuali modifiche di rilievo che potrebbero influire sull'esperienza utente con il modulo.

Example: RequiredModules = @(@{ModuleName="myDependentModule"; ModuleVersion="2.0"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Example: RequiredModules = @(@{ModuleName="myDependentModule"; RequiredVersion="1.5"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Rispondere a commenti e suggerimenti

La community valuta positivamente i proprietari di pacchetti che offrono risposte adeguate a commenti e suggerimenti. È importante rispondere agli utenti che offrono commenti e suggerimenti costruttivi, perché tali utenti sono interessati al pacchetto e cercano di migliorarlo.

In PowerShell Gallery è disponibile un'unica modalità di feedback:

  • Contact Owner (Contatta il proprietario): consente all'utente di inviare un messaggio di posta elettronica al proprietario del pacchetto. È importante che il proprietario del pacchetto controlli l'indirizzo di posta elettronica specificato con i pacchetti di PowerShell Gallery e risponda alle segnalazioni. L'unico svantaggio di questo metodo è il fatto che solo l'utente e il proprietario visualizzano questa comunicazione, pertanto è possibile che il proprietario debba rispondere molte volte alla stessa domanda.

I proprietari che rispondono ai commenti e suggerimenti in modo costruttivo sono apprezzati dalla community. Per richiedere altri informazioni, usare l'opportunità disponibile nel report. Se necessario, specificare una soluzione alternativa o indicare che il problema viene risolto da un aggiornamento.

Se in uno di questi due canali di comunicazione si rilevano comportamenti non appropriati, usare la funzionalità Segnala abusi di PowerShell Gallery per contattare gli amministratori della Gallery.

Moduli e script

La condivisione di uno script è molto utile e offre agli altri utenti esempi per la risoluzione di eventuali problemi riscontrati. Tuttavia in PowerShell Gallery gli script sono file singoli senza documentazione, esempi e test separati.

I moduli di PowerShell hanno una struttura a cartelle che consente di includere più cartelle e file nel pacchetto. La struttura del modulo consente l'inclusione degli altri pacchetti segnalati nelle procedure consigliate: guida dei cmdlet, documentazione, esempi e test. Lo svantaggio principale è che uno script all'interno di un modulo deve essere presentato e usato come una funzione. Per informazioni su come creare un modulo, vedere Writing a Windows PowerShell Module (Scrittura di un modulo Windows PowerShell).

In determinate situazioni, ad esempio con le configurazioni DSC, uno script risulta più pratico per l'utente. La procedura consigliata per le configurazioni DSC è la pubblicazione della configurazione come script con un modulo associato che contiene la documentazione, gli esempi e i test. Lo script elenca il modulo associato usando RequiredModules = @(Name of the Module). Questo approccio può essere usato con qualsiasi script.

Gli script autonomi che seguono le altre procedure consigliate risultano comunque molto utili agli altri utenti. La fornitura di documentazione basata sui commenti e del collegamento a un sito di progetto sono vivamente consigliate per la pubblicazione di uno script in PowerShell Gallery.

Nel sito di progetto l'autore può interagire direttamente con gli utenti dei pacchetti di PowerShell Gallery. Gli utenti danno la preferenza ai pacchetti che includono un sito di progetto, in quanto consente di ottenere informazioni più facilmente. Molti pacchetti in PowerShell Gallery sono sviluppati in GitHub, altri sono resi disponibili da organizzazioni con una presenza Web dedicata. Entrambi gli ambienti possono essere considerati siti di progetto.

È possibile aggiungere un collegamento includendo ProjectURI nella sezione PSData del manifesto come indicato di seguito:

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

Quando viene specificato un ProjectURI, PowerShell Gallery include un collegamento al sito di progetto sul lato sinistro della pagina del pacchetto.

Contrassegnare il pacchetto con PSEdition(s) e le piattaforme compatibili

Usare i tag seguenti per indicare agli utenti quali pacchetti funzioneranno con il loro ambiente:

  • PSEdition_Desktop: i pacchetti compatibili con Windows PowerShell
  • PSEdition_Core: pacchetti compatibili con PowerShell 6 e versioni successive
  • Windows: i pacchetti compatibili con il sistema operativo Windows
  • Linux: i pacchetti compatibili con i sistemi operativi Linux
  • MacOS: i pacchetti compatibili con i sistemi operativi Mac

L'assegnazione di tag al pacchetto con le piattaforme compatibili consentirà di includerlo nei filtri di ricerca della Gallery nel riquadro sinistro dei risultati della ricerca. Se si ospita il pacchetto in GitHub, quando si contrassegna il pacchetto, è anche possibile sfruttare l'esempio di schermata di compatibilità delle schermate di compatibilità PowerShell Gallery.

Includere test

L'inclusione di test con il codice open source è importante per gli utenti, in quanto garantisce la convalida del codice e specifica informazioni sul suo funzionamento. Inoltre garantisce agli utenti la possibilità di adattare il codice al loro ambiente senza compromettere la funzionalità originale del codice stesso.

È consigliabile creare test che supportano il framework di test Pester, sviluppato espressamente per PowerShell. Pester è disponibile in GitHub, in PowerShell Gallery ed è incluso in Windows 10, Windows Server 2016, WMF 5.0 e WMF 5.1.

Il sito di progetto Pester in GitHub include documentazione utile per la creazione di test Pester, dalle fasi iniziali alle procedure consigliate.

Gli obiettivi di code coverage dei test sono indicate nella documentazione per la creazione di un modulo di risorse di qualità elevata. Il valore di code coverage consigliato per lo unit test è 70%.

Tutti i pacchetti pubblicati in PowerShell Gallery devono specificare le condizioni di licenza o essere vincolati dalla licenza inclusa nelle condizioni d'uso alla voce Exhibit A (Allegato A). L'approccio migliore per specificare una licenza diversa è l'inclusione di un collegamento alla licenza tramite LicenseURI in PSData. Per altre informazioni, vedere Manifesto dei pacchetti e interfaccia utente di Gallery.

PrivateData = @{
    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = @('.net','acl','active-directory')

        # A URL to the license for this module.
        LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

Firmare il codice

La firma del codice offre agli utenti il massimo livello di garanzia per quanto riguarda l'autore del pacchetto e l'autenticità del codice acquisito. Per altre informazioni generali sulla firma del codice, vedere Introduction to Code Signing (Introduzione alla firma del codice). PowerShell supporta la convalida della firma del codice con due approcci principali:

  • Firma dei file di script
  • Firma di moduli mediante catalogo

La firma dei file di PowerShell è un metodo consolidato e garantisce che il codice eseguito è stato generato da una fonte attendibile e non è stato modificato. Informazioni dettagliate sulla firma dei file di script di PowerShell sono disponibili nell'articolo About signing (Informazioni sulla firma). Per riassumere, è possibile aggiungere una firma a qualsiasi file .PS1 convalidato da PowerShell quando viene caricato lo script. È possibile vincolare PowerShell all'uso di script firmati con i cmdlet dei criteri di esecuzione.

La firma di moduli mediante catalogo è una funzionalità aggiunta in PowerShell 5.1. Le modalità per la firma di un modulo sono descritte nell'argomento Cmdlet di catalogo. Per riassumere, la firma mediante catalogo viene eseguita creando un file di catalogo che contiene un valore hash per ogni file nel modulo, quindi firmando questo file.

I cmdlet di PowerShellGetPublish-Module, Install-Modulee Update-Module verificheranno la firma per assicurarsi che sia valido, quindi verificare che il valore hash per ogni pacchetto corrisponda a quello presente nel catalogo. Save-Module non convalida una firma. Se nel sistema è installata una versione precedente del modulo, Install-Module verifica che l'autorità di firma della nuova versione corrisponda a quella dell'installazione precedente. Se il pacchetto non ha una firma tramite catalogo, Install-Module e Update-Module usano la firma in un file .PSD1. La firma tramite catalogo può essere usata insieme alla firma dei file di script ma non la sostituisce. PowerShell non convalida le firme del catalogo al caricamento del modulo.

Osservare le linee guida SemVer per il controllo delle versioni

SemVer è una convenzione pubblica che descrive come strutturare e cambiare una versione per facilitare l'interpretazione delle modifiche. La versione del pacchetto deve essere inclusa nei dati del manifesto.

  • La versione deve essere strutturata con tre blocchi numerici separati da punti, ad esempio 0.1.1 o 4.11.192.
  • Le versioni che iniziano con 0 indicano che il pacchetto non è ancora pronto per la produzione e il primo numero dovrebbe iniziare con 0 solo se è l'unico numero usato.
  • La modifica del primo numero (da 1.9.9999 a 2.0.0) indica modifiche strutturali di primaria importanza da una versione alla successiva.
  • La modifica del secondo numero (da 1.1 a 1.2) indica modifiche a livello di funzionalità, ad esempio l'aggiunta di nuovi cmdlet a un modulo.
  • La modifica del terzo numero indica modifiche meno importanti, ad esempio l'aggiunta di nuovi parametri, esempi aggiornati o nuovi test.
  • Per la creazione di elenchi di versioni in PowerShell le versioni vengono ordinate come stringhe, quindi 1.01.0 verrà considerato maggiore di 1.001.0.

L'applicazione PowerShell è stata creata prima della pubblicazione di SemVer, pertanto supporta la maggior parte degli elementi di SemVer ma non tutti, in particolare:

  • Non supporta le stringhe di versione provvisoria nei numeri di versione. Questo è utile quando un autore vuole rilasciare una versione di anteprima di una nuova versione principale dopo aver rilasciato la versione 1.0.0. Questa funzionalità verrà supportata in una versione futura dei cmdlet di PowerShell Gallery e PowerShellGet.
  • PowerShell e PowerShell Gallery supportano le stringhe di versione con 1, 2 e 4 segmenti. Molti moduli meno recenti non seguivano queste linee guida e le versioni dei prodotti Microsoft includono le informazioni sulla build in un quarto blocco di numeri, ad esempio 5.1.14393.1066. Dal punto di vista del controllo delle versioni, queste differenze vengono ignorate.

Eseguire test usando un repository locale

PowerShell Gallery non è progettato per essere usato come destinazione per il testing del processo di pubblicazione. Il modo migliore per testare l'intero processo di pubblicazione in PowerShell Gallery prevede la configurazione e l'uso di un repository personale locale. Questa operazione può essere eseguita in svariati modi, ad esempio:

  • Configurare un'istanza locale di PowerShell Gallery usando il progetto di PS Gallery privato in GitHub. Questo progetto di anteprima consente di configurare un'istanza di PowerShell Gallery che è possibile controllare e usare per i test.
  • Configurare un repository NuGet interno. Questa alternativa richiede un maggiore impegno per la configurazione, ma offre il vantaggio di poter convalidare un maggior numero di requisiti, in particolare l'uso di una chiave API e la presenza o meno delle dipendenze nella destinazione durante la pubblicazione.
  • Configurare una condivisione file come repository di test. Si tratta di una soluzione semplice da configurare, ma trattandosi di una condivisione file, le convalide indicate in precedenza non verranno eseguite. Uno dei vantaggi potenziali in questo caso è che la condivisione file non controlla la chiave API obbligatoria, pertanto è possibile usare la stessa chiave usata per la pubblicazione in PowerShell Gallery.

Con una qualsiasi di queste soluzioni, usare Register-PSRepository per definire un nuovo repository che a sua volta viene usato nel parametro -Repository per Publish-Module.

Per la pubblicazione di test è importante evidenziare un altro aspetto: nessun pacchetto pubblicato in PowerShell Gallery può essere eliminato senza l'assistenza del team operativo, che dovrà confermare che non esistano dipendenze per il pacchetto che si vuole pubblicare. Per questo motivo PowerShell Gallery non è supportato come destinazione di testing e qualsiasi autore che prova a usarlo a questo scopo verrà contattato da Microsoft.

Usare PowerShellGet per la pubblicazione

È consigliabile che gli autori della pubblicazione usino i cmdlet Publish-Module e Publish-Script quando lavorano con PowerShell Gallery. PowerShellGet è stato creato per evitare che vengano memorizzate informazioni importanti sull'installazione da e la pubblicazione in PowerShell Gallery. In alcuni casi, gli autori della pubblicazione hanno scelto di ignorare PowerShellGet e usare il client NuGet o i cmdlet PackageManagement invece di Publish-Module. Molti dettagli vengono facilmente omessi, il che genera richieste di supporto di vario genere.

Se per qualsiasi motivo non è possibile usare Publish-Module o Publish-Script, inviare una notifica. Segnalare un problema nel repository GitHub di PowerShellGet e specificare i dettagli che determinano la scelta di NuGet o PackageManagement.

L'approccio più efficace per i pacchetti pubblicati in PowerShell Gallery è il seguente:

  • Eseguire lo sviluppo iniziale in un sito di progetto open-source. Il team di PowerShell usa GitHub.
  • Usare commenti e suggerimenti da revisori e PowerShell Script Analyzer per ottenere lo stato stabile del codice.
  • Includere documentazione, per comunicare agli altri utenti come usare il codice.
  • Testare l'azione di pubblicazione usando un repository locale.
  • Pubblicare una versione stabile o alfa in PowerShell Gallery e includere la documentazione e il collegamento al sito del progetto.
  • Raccogliere il feedback e sviluppare il codice nel sito di progetto, quindi pubblicare gli aggiornamenti stabili in PowerShell Gallery.
  • Aggiungere esempi e test Pester nel progetto e nel modulo.
  • Decidere se firmare il codice del pacchetto.
  • Quando si ritiene che il progetto sia pronto per l'uso in un ambiente di produzione, pubblicare la versione 1.0.0 in PowerShell Gallery.
  • Continuare a raccogliere commenti e suggerimenti e sviluppare ulteriormente il codice in base all'input degli utenti.