Linee guida e procedure consigliate per la pubblicazione di PowerShellGallery

  • Articolo

Questo articolo descrive i passaggi consigliati usati dai team Microsoft per garantire che i pacchetti pubblicati in PowerShell Gallery vengano ampiamente adottati e forniscano un valore elevato agli utenti, in base al modo in cui PowerShell Gallery gestisce i dati del manifesto e il feedback di un numero elevato di utenti di PowerShell Gallery. I pacchetti pubblicati seguendo queste linee guida avranno maggiori probabilità di essere installati, attendibili e attirare più utenti.

Di seguito sono riportate le linee guida per ciò che rende un buon pacchetto di PowerShell Gallery, quali impostazioni del manifesto facoltative sono più importanti, migliorando il codice con commenti e suggerimenti dei revisori iniziali e PowerShell Script Analyzer, controllo delle versioni del modulo, documentazione, test ed esempi per l'uso di ciò che è stato condiviso. Gran parte di questa documentazione segue le linee guida per la pubblicazione di moduli di risorse DSC di alta qualità .

Per i meccanismi di pubblicazione di un pacchetto in PowerShell Gallery, vedere Creazione e pubblicazione di un pacchetto.

Il feedback su queste linee guida è accolto. Se si hanno commenti e suggerimenti, aprire i problemi nel repository della documentazione di GitHub .

Procedure consigliate per la pubblicazione di pacchetti

Le procedure consigliate seguenti sono quelle che gli utenti degli elementi di PowerShell Gallery dicono importanti e sono elencate in ordine di priorità nominale. È molto più probabile che i pacchetti che seguono queste linee guida vengano scaricati e adottati da altri utenti.

  • Usare PSScriptAnalyzer
  • Includere documentazione ed esempi
  • Essere reattivi ai commenti e suggerimenti
  • Fornire moduli anziché script
  • Fornire collegamenti a un sito di progetto
  • Contrassegna il pacchetto con le piattaforme e le piattaforme PSEdition compatibili
  • Includere test con i moduli
  • Includi e/o collega alle condizioni di licenza
  • Firmare il codice
  • Seguire linee guida SemVer per il controllo delle versioni
  • Usare tag comuni, come documentato in Tag comuni di PowerShell Gallery
  • Testare la pubblicazione usando un repository locale
  • Usare PowerShellGet per pubblicare

Ognuna di queste è descritta brevemente nelle sezioni seguenti.

Usare PSScriptAnalyzer

PSScriptAnalyzer è uno strumento di analisi del codice statico gratuito che funziona nel codice di PowerShell. PSScriptAnalyzer identificherà i problemi più comuni riscontrati nel codice di PowerShell e spesso è consigliabile risolvere il problema. Lo strumento è facile da usare e classifica i problemi come Errori (grave, deve essere risolto), Avviso (deve essere esaminato e deve essere risolto) e Informazioni (vale la pena consultare le procedure consigliate). Tutti i pacchetti pubblicati in PowerShell Gallery verranno analizzati usando PSScriptAnalyzere tutti gli errori verranno segnalati al proprietario e devono essere risolti.

La procedura consigliata consiste nell'eseguire Invoke-ScriptAnalyzer con -Recurse e -Severity avviso.

Esaminare i risultati e assicurarsi che:

  • Tutti gli errori vengono corretti o risolti nella documentazione.
  • Tutti gli avvisi vengono esaminati e risolti, se applicabile.

Gli utenti che scaricano pacchetti da PowerShell Gallery sono fortemente invitati a eseguire PSScriptAnalyzer e valutare tutti gli errori e gli avvisi. È molto probabile che gli utenti contattino i proprietari dei pacchetti se vedono che si è verificato un errore segnalato da PSScriptAnalyzer. Se c'è un motivo interessante per cui il pacchetto mantiene il codice contrassegnato come errore, aggiungere tali informazioni alla documentazione per evitare di dover rispondere più volte alla stessa domanda.

Includere documentazione ed esempi

La documentazione e gli esempi rappresentano il modo migliore per garantire che gli utenti possano sfruttare qualsiasi codice condiviso.

La documentazione è la cosa più utile da includere nei pacchetti pubblicati in PowerShell Gallery. Gli utenti in genere ignorano i pacchetti senza documentazione, perché l'alternativa consiste nel leggere il codice per comprendere che cos'è il pacchetto e come usarlo. Sono disponibili diversi articoli su come fornire la documentazione con i pacchetti PowerShell, tra cui:

  • Le linee guida per fornire assistenza sono disponibili in Come scrivere la Guida dei cmdlet.
  • Creazione della Guida dei cmdlet, che rappresenta l'approccio migliore per qualsiasi script, funzione o cmdlet di PowerShell. Per informazioni su come creare la Guida dei cmdlet, iniziare con Come scrivere la Guida dei cmdlet. Per aggiungere assistenza all'interno di uno script, vedere Informazioni sulla Guida basata su commenti.
  • Molti moduli includono anche la documentazione in formato testo, ad esempio i file MarkDown. Ciò può essere particolarmente utile quando è presente un sito di progetto in GitHub, in cui Markdown è un formato molto usato. La procedura consigliata consiste nell'usare Markdown con sapore GitHub.

Gli esempi mostrano agli utenti il modo in cui il pacchetto deve essere usato. Molti sviluppatori diranno che esaminano esempi prima della documentazione per comprendere come usare un elemento. I tipi migliori di esempi mostrano l'uso di base, oltre a un caso d'uso realistico simulato e il codice è ben commentato. Gli esempi per i moduli pubblicati in PowerShell Gallery devono trovarsi in una cartella Examples nella radice del modulo.

Un modello valido per gli esempi è disponibile nel modulo PSDscResource nella cartella Examples\RegistryResource. Ci sono quattro casi d'uso di esempio con una breve descrizione nella parte superiore di ogni file che documenta ciò che viene dimostrato.

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 l'utente. Per specificare i moduli dipendenti, è necessario usare il campo modulo richiesto nel manifesto del modulo. Verranno caricati tutti i moduli elencati nell'ambiente globale prima di importare il modulo, a meno che non siano già stati caricati. Ad esempio, alcuni moduli potrebbero essere già caricati da un modulo diverso. È anche possibile specificare una versione specifica da caricare usando il campo RequiredVersion anziché il campo ModuleVersion. Quando si usa ModuleVersion, verrà caricata la versione più recente disponibile con almeno la versione specificata. Quando non si usa il campo RequiredVersion , per specificare una versione specifica è importante monitorare gli aggiornamenti delle versioni per il modulo richiesto. È particolarmente importante tenere presente 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 ai commenti e suggerimenti

I proprietari di pacchetti che rispondono correttamente al feedback sono altamente apprezzati dalla community. Gli utenti che forniscono feedback costruttivo sono importanti per rispondere, in quanto sono interessati abbastanza al pacchetto per tentare di migliorarlo.

In PowerShell Gallery è disponibile un metodo di feedback:

  • Proprietario contatto: consente a un utente di inviare un messaggio di posta elettronica al proprietario del pacchetto. Il proprietario del pacchetto è importante monitorare l'indirizzo di posta elettronica usato con i pacchetti di PowerShell Gallery e rispondere ai problemi generati. Uno svantaggio di questo metodo è che solo l'utente e il proprietario vedranno mai la comunicazione, quindi il proprietario potrebbe dover rispondere alla stessa domanda molte volte.

I proprietari che rispondono al feedback in modo costruttivo sono apprezzati dalla community. Usare l'opportunità nel report per richiedere altre informazioni. Se necessario, fornire una soluzione alternativa o identificare se un aggiornamento risolve un problema.

Se si verifica un comportamento inappropriato da uno di questi canali di comunicazione, usare la funzionalità Segnala abusi di PowerShell Gallery per contattare gli amministratori della raccolta.

Moduli e script

La condivisione di uno script con altri utenti è ideale e offre ad altri utenti esempi di come risolvere i problemi che potrebbero avere. Il problema è che gli script in PowerShell Gallery sono singoli file senza documentazione, esempi e test separati.

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

In alcune situazioni uno script offre un'esperienza migliore per l'utente, in particolare con configurazioni DSC. La procedura consigliata per le configurazioni DSC consiste nel pubblicare la configurazione come script con un modulo associato che contiene la documentazione, gli esempi e i test. Lo script elenca il modulo a corredo usando RequiredModules = @(Name of the Module). Questo approccio può essere usato con qualsiasi script.

Gli script autonomi che seguono le altre procedure consigliate forniscono valore reale ad altri utenti. Quando si pubblica uno script in PowerShell Gallery, è consigliabile fornire documentazione basata su commenti e un collegamento a un sito di progetto.

Un sito di progetto è il punto in cui un editore può interagire direttamente con gli utenti dei pacchetti di PowerShell Gallery. Gli utenti preferiscono pacchetti che forniscono questo, in quanto consentono di ottenere informazioni sul pacchetto più facilmente. Molti pacchetti in PowerShell Gallery vengono sviluppati in GitHub, altri vengono forniti dalle organizzazioni con una presenza Web dedicata. Ognuno di questi può essere considerato un sito di progetto.

L'aggiunta di un collegamento viene eseguita 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 fornito un ProjectURI, PowerShell Gallery includerà un collegamento al sito del progetto sul lato sinistro della pagina del pacchetto.

Contrassegna il pacchetto con le piattaforme e le piattaforme PSEdition compatibili

Usare i tag seguenti per illustrare agli utenti quali pacchetti funzioneranno correttamente con il proprio ambiente:

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

Contrassegnando il pacchetto con le piattaforme compatibili che verrà incluso nei filtri di ricerca della raccolta nel riquadro sinistro dei risultati della ricerca. Se si ospita il pacchetto in GitHub, quando si contrassegna il pacchetto, è anche possibile sfruttare i vantaggi di schermate di compatibilità di PowerShell Galleryesempio di schermata di compatibilità.

Includi test

L'inclusione di test con codice open source è importante per gli utenti, in quanto garantisce la convalida e fornisce informazioni sul funzionamento del codice. Consente anche agli utenti di assicurarsi che non interrompano la funzionalità originale se modificano il codice per adattarsi all'ambiente.

È consigliabile scrivere i test per sfruttare il framework di test pester, progettato appositamente per PowerShell. Pester è disponibile in GitHub, PowerShell Gallerye viene fornito in Windows 10, Windows Server 2016, WMF 5.0 e WMF 5.1.

Il sito del progetto Pester in GitHub include una buona documentazione sulla scrittura di test pester, dall'introduzione alle procedure consigliate.

Le destinazioni per la copertura dei test vengono evidenziate nella documentazione Modulo risorse di alta qualità, con 70% code coverage unit test consigliato.

Tutti i pacchetti pubblicati in PowerShell Gallery devono specificare le condizioni di licenza o essere vincolati dalla licenza inclusa nella Condizioni per l'utilizzo in Esporre un. L'approccio migliore per specificare una licenza diversa consiste nel fornire un collegamento alla licenza usando il LicenseURI in PSData. Per altre informazioni, vedere manifesto dei pacchetti e interfaccia utente della raccolta.

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 chi ha pubblicato il pacchetto e che la copia del codice acquisito è esattamente ciò che l'editore ha rilasciato. Per altre informazioni sulla firma del codice in genere, vedere Introduzione alla firma del codice. PowerShell supporta la convalida della firma del codice tramite due approcci principali:

  • Firma dei file di script
  • Firma del catalogo di un modulo

La firma dei file di PowerShell è un approccio ben definito per garantire che il codice eseguito sia stato prodotto da un'origine affidabile e non sia stato modificato. Per informazioni dettagliate su come firmare i file di script di PowerShell, vedere l'articolo Informazioni sulla firma. In panoramica, è possibile aggiungere una firma a qualsiasi file di .PS1 convalidato da PowerShell al caricamento dello script. PowerShell può essere vincolato usando i cmdlet criteri di esecuzione per garantire l'uso di script firmati.

I moduli di firma del catalogo sono una funzionalità aggiunta a PowerShell nella versione 5.1. Come firmare un modulo è illustrato nell'articolo cmdlet del catalogo di . In panoramica, la firma del catalogo viene eseguita creando un file di catalogo contenente un valore hash per ogni file nel modulo e quindi firmando tale file.

I cmdlet 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 conferma che l'autorità di firma per la nuova versione corrisponde a quella installata in precedenza. Install-Module e Update-Module useranno la firma in un file .PSD1 se il pacchetto non è firmato dal catalogo. La firma del catalogo funziona con , ma non sostituisce i file di script di firma. PowerShell non convalida le firme del catalogo in fase di caricamento del modulo.

Seguire le linee guida di SemVer per il controllo delle versioni

SemVer è una convenzione pubblica che descrive come strutturare e modificare una versione per consentire un'interpretazione semplice delle modifiche. La versione del pacchetto deve essere inclusa nei dati del manifesto.

  • La versione deve essere strutturata come tre blocchi numerici separati da punti, come in 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 deve iniziare solo con 0 se è l'unico numero usato.
  • Le modifiche apportate al primo numero (1.9.9999 a 2.0.0) indicano modifiche importanti e di rilievo tra le versioni.
  • Le modifiche apportate al secondo numero (1.1 a 1.2) indicano modifiche a livello di funzionalità, ad esempio l'aggiunta di nuovi cmdlet a un modulo.
  • Le modifiche apportate al terzo numero indicano modifiche non di rilievo, ad esempio nuovi parametri, campioni aggiornati o nuovi test.
  • Quando si elencano le versioni, PowerShell ordina le versioni come stringhe, quindi 1.01.0 verrà considerato maggiore di 1.001.0.

PowerShell è stato creato prima della pubblicazione di SemVer, quindi offre il supporto per la maggior parte, ma non per tutti gli elementi di SemVer, in particolare:

  • Non supporta stringhe non definitive nei numeri di versione. Ciò è utile quando un editore desidera distribuire una versione di anteprima di una nuova versione principale dopo aver fornito una versione 1.0.0. Questa funzionalità sarà supportata in una versione futura di PowerShell Gallery e cmdlet powerShellGet.
  • PowerShell e PowerShell Gallery consentono stringhe di versione con 1, 2 e 4 segmenti. Molti moduli iniziali non hanno seguito le linee guida e le versioni del prodotto di Microsoft includono informazioni sulla compilazione come un quarto blocco di numeri (ad esempio 5.1.14393.1066). Dal punto di vista del controllo delle versioni, queste differenze vengono ignorate.

Eseguire il test usando un repository locale

PowerShell Gallery non è progettato per essere una destinazione per il test del processo di pubblicazione. Il modo migliore per testare il processo end-to-end di pubblicazione in PowerShell Gallery consiste nel configurare e usare il proprio repository locale. Questa operazione può essere eseguita in diversi modi, tra cui:

  • Configurare un'istanza locale di PowerShell Gallery usando il progetto PS Private Gallery 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 operazione richiederà più lavoro per la configurazione, ma avrà il vantaggio di convalidare alcuni altri requisiti, in particolare convalidando l'uso di una chiave API e indipendentemente dal fatto che le dipendenze siano presenti nella destinazione durante la pubblicazione.
  • Configurare una condivisione file come repository di test. Questa operazione è facile da configurare, ma poiché si tratta di una condivisione file, le convalide indicate in precedenza non verranno eseguite. Un potenziale vantaggio in questo caso è che la condivisione file non controlla la chiave API richiesta, quindi è possibile usare la stessa chiave usata per pubblicare in PowerShell Gallery.

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

Un altro punto sulla pubblicazione dei test: qualsiasi pacchetto pubblicato in PowerShell Gallery non può essere eliminato senza assistenza dal team operativo, che conferma che nulla dipende dal pacchetto che si vuole pubblicare. Per questo motivo, PowerShell Gallery non è supportato come destinazione di test e contatterà qualsiasi editore che lo faccia.

Usare PowerShellGet per pubblicare

È consigliabile che gli editori usino i cmdlet Publish-Module e Publish-Script quando si usa PowerShell Gallery. PowerShellGet è stato creato per evitare di ricordare dettagli importanti sull'installazione e la pubblicazione in PowerShell Gallery. In alcuni casi, gli editori hanno scelto di ignorare PowerShellGet e di usare il client di NuGet o cmdlet packageManagement anziché . Esistono diversi dettagli che possono risultare facilmente mancanti, con un'ampia gamma di richieste di supporto.

Se c'è un motivo per cui non è possibile usare Publish-Module o Publish-Script, segnalarlo. Segnalare un problema nel repository PowerShellGet GitHub e specificare i dettagli che causano la scelta di NuGet o PackageManagement.

L'approccio più efficace trovato 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 dei revisori e powerShell Script Analyzer per ottenere lo stato stabile del codice.
  • Includere la documentazione, in modo che altri utenti sappiano come usare il lavoro.
  • Testare l'azione di pubblicazione usando un repository locale.
  • Pubblicare una versione stabile o alfa in PowerShell Gallery, assicurandosi di includere la documentazione e il collegamento al sito del progetto.
  • Raccogliere commenti e suggerimenti e scorrere il codice nel sito del progetto, quindi pubblicare aggiornamenti stabili in PowerShell Gallery.
  • Aggiungere esempi e test pester nel progetto e nel modulo.
  • Decidere se si vuole scrivere codice per firmare il pacchetto.
  • Quando si ritiene che il progetto sia pronto per l'uso in un ambiente di produzione, pubblicare una versione 1.0.0 in PowerShell Gallery.
  • Continuare a raccogliere commenti e suggerimenti e scorrere il codice in base all'input dell'utente.