Linee guida e procedure consigliate per la pubblicazione in PowerShell GalleryPowerShellGallery Publishing Guidelines and Best Practices

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.This article describes recommended steps used by Microsoft teams to ensure the packages published to the PowerShell Gallery will be widely adopted and provide high value to users, based on how the PowerShell Gallery handles manifest data and on feedback from large numbers of PowerShell Gallery users. I pacchetti pubblicati attenendosi a queste linee guida hanno maggiori probabilità di essere installati e considerati attendibili e attraggono un numero maggiore di utenti.Packages that are published following these guidelines will be more likely to be installed, trusted, and attract more users.

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.Included below are guidelines for what makes a good PowerShell Gallery package, what optional Manifest settings are most important, improving your code with feedback from initial reviewers and Powershell Script Analyzer, versioning your module, documentation, tests and examples for how to use what you have shared. Questa documentazione segue in gran parte le linee guida per la pubblicazione di moduli risorsa DSC di qualità.Much of this documentation follows the guidelines for publishing High Quality DSC Resource Modules.

Per informazioni sulle modalità di pubblicazione di un pacchetto in PowerShell Gallery vedere Creazione e pubblicazione di un pacchetto.For the mechanics of publishing a package to the PowerShell Gallery, see Creating and Publishing a Package.

Sono graditi i commenti e i suggerimenti relativi a queste linee guida.Feedback on these guidelines is welcomed. Per pubblicare osservazioni è possibile aprire un caso nell'archivio della documentazione GitHub.If you do have feedback, please open issues in our GitHub documentation repository.

Procedure consigliate per la pubblicazione di pacchettiBest practices for publishing packages

Le seguenti procedure consigliate sono state segnalate come importanti dagli utenti degli elementi di PowerShell Gallery e sono elencate in ordine di priorità nominale.The following best practices are what the users of PowerShell Gallery items say is important, and are listed in nominal priority order. I pacchetti creati usando queste linee guida hanno molte più probabilità di essere scaricati e adottati da altri utenti.Packages that follow these guidelines are far more likely to be downloaded and adopted by others.

  • Usare PSScriptAnalyzerUse PSScriptAnalyzer
  • Includere documentazione ed esempiInclude documentation and examples
  • Rispondere a commenti e suggerimentiBe responsive to feedback
  • Includere moduli anziché scriptProvide modules rather than scripts
  • Includere un collegamento a un sito di progettoProvide links to a project site
  • Contrassegnare il pacchetto con PSEdition(s) e le piattaforme compatibiliTag your package with the compatible PSEdition(s) and platforms
  • Includere test con i moduliInclude tests with your modules
  • Includere e/o collegare condizioni di licenzaInclude and/or link to license terms
  • Firmare il codiceSign your code
  • Osservare le linee guida SemVer per il controllo delle versioniFollow SemVer guidelines for versioning
  • Usare tag comuni, documentati nei tag comuni di PowerShell GalleryUse common tags, as documented in Common PowerShell Gallery tags
  • Pubblicazione di test usando un repository localeTest publishing using a local repository
  • Usare PowerShellGet per la pubblicazioneUse PowerShellGet to publish

Ogni voce viene descritta brevemente nelle sezioni che seguono.Each of these is covered briefly in the sections below.

Usare PSScriptAnalyzerUse PSScriptAnalyzer

PSScriptAnalyzer è uno strumento di analisi del codice statico gratuito che funziona con il codice PowerShell.PSScriptAnalyzer is a free static code analysis tool that works on PowerShell code. PSScriptAnalyzer identifica i problemi più comuni del codice di PowerShell e in molti casi offre un suggerimento per la risoluzione.PSScriptAnalyzer will identify the most common issues seen in PowerShell code, and often a recommendation for how to fix the issue. 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).The tool is easy to use, and categorizes the issues as Errors (severe, must be addressed), Warning (need to be reviewed and should be addressed), and Information (worth checking out for best practices). Tutti i pacchetti pubblicati in PowerShell Gallery vengono esaminati con PSScriptAnalyzer e gli eventuali errori vengono restituiti al proprietario e devono essere risolti.All packages published to the PowerShell Gallery will be scanned using PSScriptAnalyzer , and any errors will be reported back to the owner and must be addressed.

La procedura consigliata consiste nell'eseguire Invoke-ScriptAnalyzer con -Recurse e -Severity impostata su Warning (Avviso).The best practice is to run Invoke-ScriptAnalyzer with -Recurse and -Severity Warning.

Esaminare i risultati e verificare quanto segue:Review the results, and ensure that:

  • Tutti i problemi di tipo Error sono stati corretti o sono illustrati nella documentazione.All Errors are corrected or addressed in your documentation.
  • Tutti i problemi di tipo Warning sono stati esaminati e risolti se necessario.All Warnings are reviewed, and addressed where applicable.

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.Users who download packages from the PowerShell Gallery are strongly encouraged to run PSScriptAnalyzer and evaluate all Errors and Warnings. Se un utente nota che PSScriptAnalyzer segnala un errore, probabilmente tenterà di contattare il proprietario del pacchetto corrispondente.Users are very likely to contact package owners if they see that there's an error reported by PSScriptAnalyzer. 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.If there's a compelling reason for your package to keep code that is flagged as an error, add that information to your documentation to avoid having to answer the same question many times.

Includere documentazione ed esempiInclude documentation and examples

La documentazione e gli esempi sono il metodo migliore per consentire agli utenti di trarre il massimo vantaggio dal codice condiviso.Documentation and examples are the best way to ensure users can take advantage of any shared code.

La documentazione è l'elemento più importante da includere nei pacchetti pubblicati in PowerShell Gallery.Documentation is the most helpful thing to include in packages published to the 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.Users will generally bypass packages without documentation, as the alternative is to read the code to understand what the package is and how to use it. Sono disponibili vari articoli che illustrano come includere documentazione con i pacchetti di PowerShell, tra cui:There are several articles available about how to provide documentation with PowerShell packages, including:

  • Suggerimenti per la creazione della documentazione sono disponibili in How to Write Cmdlet Help (Come scrivere documentazione per i cmdlet).Guidelines for providing help are in How to Write Cmdlet Help.
  • La creazione di documentazione per i cmdlet è l'approccio migliore per script, funzioni o cmdlet di PowerShell.Creating cmdlet help, which is the best approach for any PowerShell script, function, or cmdlet. Per informazioni su come creare la Guida per i cmdlet, iniziare da How to Write Cmdlet Help (Come scrivere la Guida per i cmdlet).For information about how to create cmdlet help, start with How to Write Cmdlet Help. Per aggiungere elementi di documentazione in uno script vedere About Comment Based Help (Informazioni sulla documentazione basata sui commenti).To add help within a script, see About Comment Based Help.
  • Molti moduli includono anche documentazione in formato testo, ad esempio file Markdown.Many modules also include documentation in text format, such as MarkDown files. Questa soluzione può essere utile se è disponibile un sito del progetto in GitHub, dove Markdown è un formato molto usato.This can be particularly helpful when there's a project site in GitHub, where Markdown is a heavily used format. La procedura consigliata è l'uso di Markdown per GitHub.The best practice is to use GitHub-flavored Markdown.

Gli esempi indicano agli utenti come usare il pacchetto.Examples show users how the package is intended to be used. Secondo molti sviluppatori, per capire come usare un elemento è utile vedere gli esempi prima della documentazione.Many developers will say that they look at examples before documentation to understand how to use something. I migliori esempi indicano il funzionamento di base e un caso d'uso simulato realistico e includono commenti dettagliati al codice.The best types of examples show basic use, plus a simulated realistic use case, and the code is well-commented. Gli esempi per i moduli pubblicati in PowerShell Gallery dovrebbero essere inclusi in una cartella Examples sotto la cartella radice del modulo.Examples for modules published to the PowerShell Gallery should be in an Examples folder under the module root.

Un modello ottimale per gli esempi è disponibile nel modulo PSDscResource nella cartella Examples\RegistryResource.A good pattern for examples can be found in the PSDscResource module under the Examples\RegistryResource folder. All'inizio di ogni file sono presenti quattro casi d'uso di esempio, corredati da una breve descrizione.There are four sample use cases with a brief description at the top of each file that documents what is being demonstrated.

Gestire le dipendenzeManage Dependencies

È importante specificare i moduli da cui dipende il modulo nel manifesto del modulo.It's important to specify modules that your module is dependent on in the Module Manifest. In questo modo l'utente finale non deve preoccuparsi di installare le versioni appropriate dei moduli da cui dipende il proprio modulo.This allows the end user to not have to worry about installing the proper versions of modules that yours take a dependency on. Per specificare i moduli dipendenti è necessario usare il campo modulo obbligatorio nel manifesto del modulo.To specify dependent modules, you should use the required module field in the module manifest. Prima di importare il modulo verranno così caricati tutti i moduli elencati nell'ambiente globale, a meno che non siano già stati caricati.This will load any listed modules into the global environment prior to importing your module unless they've already been loaded. Ad esempio alcuni moduli potrebbero essere già stati caricati da un modulo diverso.For example, some modules may already be loaded by a different module. È anche possibile indicare una versione specifica da caricare usando il campo RequiredVersion invece del campo ModuleVersion.It's also possible to specify a specific version to load using the RequiredVersion field rather than the ModuleVersion field. Quando si usa ModuleVersion viene caricata la versione più recente disponibile, comunque non inferiore alla versione specificata.When using ModuleVersion , it will load the newest version available with a minimum of the version specified. Quando non si usa il campo RequiredVersion per indicare una versione specifica, è importante monitorare gli aggiornamenti delle versioni per il modulo obbligatorio.When not using the RequiredVersion field, to specify a specific version it's important to monitor version updates to the required module. È di fondamentale importanza essere a conoscenza di eventuali modifiche di rilievo che potrebbero influire sull'esperienza utente con il modulo.It's especially important to be aware of any breaking changes that could affect the user experience with your module.

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 suggerimentiRespond to feedback

La community valuta positivamente i proprietari di pacchetti che offrono risposte adeguate a commenti e suggerimenti.Package owners who respond properly to feedback are highly valued by the community. È importante rispondere agli utenti che offrono commenti e suggerimenti costruttivi, perché tali utenti sono interessati al pacchetto e cercano di migliorarlo.Users who provide constructive feedback are important to respond to, as they're interested enough in the package to try to help improve it.

In PowerShell Gallery è disponibile un'unica modalità di feedback:There is one feedback method available in the PowerShell Gallery:

  • Contact Owner (Contatta il proprietario): consente all'utente di inviare un messaggio di posta elettronica al proprietario del pacchetto.Contact Owner: This allows a user to send an email to the package owner. È importante che il proprietario del pacchetto controlli l'indirizzo di posta elettronica specificato con i pacchetti di PowerShell Gallery e risponda alle segnalazioni.As a package owner, is important to monitor the email address used with the PowerShell Gallery packages, and respond to issues that are raised. 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.The one disadvantage to this method is that only the user and owner will ever see the communication, so the owner may have to answer the same question many times.

I proprietari che rispondono ai commenti e suggerimenti in modo costruttivo sono apprezzati dalla community.Owners who respond to feedback constructively are appreciated by the community. Per richiedere altri informazioni, usare l'opportunità disponibile nel report.Use the opportunity in the report to request more information. Se necessario, specificare una soluzione alternativa o indicare che il problema viene risolto da un aggiornamento.If needed, provide a workaround, or identify if an update fixes a problem.

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.If there's inappropriate behavior observed from either of these communication channels, use the Report Abuse feature of the PowerShell Gallery to contact the Gallery Administrators.

Moduli e scriptModules Versus Scripts

La condivisione di uno script è molto utile e offre agli altri utenti esempi per la risoluzione di eventuali problemi riscontrati.Sharing a script with other users is great, and provides others with examples of how to solve problems they may have. Tuttavia in PowerShell Gallery gli script sono file singoli senza documentazione, esempi e test separati.The issue is that scripts in the PowerShell Gallery are single files without separate documentation, examples, and tests.

I moduli di PowerShell hanno una struttura a cartelle che consente di includere più cartelle e file nel pacchetto.PowerShell Modules have a folder structure that allows multiple folders and files to be included with the package. La struttura del modulo consente l'inclusione degli altri pacchetti segnalati nelle procedure consigliate: guida dei cmdlet, documentazione, esempi e test.The module structure enables including the other packages we list as best practices: cmdlet help, documentation, examples, and tests. Lo svantaggio principale è che uno script all'interno di un modulo deve essere presentato e usato come una funzione.The biggest disadvantage is that a script inside a module must be exposed and used as a function. Per informazioni su come creare un modulo, vedere Writing a Windows PowerShell Module (Scrittura di un modulo Windows PowerShell).For information on how to create a module, see Writing a Windows PowerShell Module.

In determinate situazioni, ad esempio con le configurazioni DSC, uno script risulta più pratico per l'utente.There are situations where a script provides a better experience for the user, particularly with DSC configurations. 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.The best practice for DSC configurations is to publish the configuration as a script with an accompanying module that contains the docs, examples, and tests. Lo script elenca il modulo associato usando RequiredModules = @(Name of the Module).The script lists the accompanying module using RequiredModules = @(Name of the Module). Questo approccio può essere usato con qualsiasi script.This approach can be used with any script.

Gli script autonomi che seguono le altre procedure consigliate risultano comunque molto utili agli altri utenti.Standalone scripts that follow the other best practices provide real value to other users. 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.Providing comment-based documentation and a link to a Project Site are highly recommended when publishing a script to the PowerShell Gallery.

Nel sito di progetto l'autore può interagire direttamente con gli utenti dei pacchetti di PowerShell Gallery.A Project Site is where a publisher can interact directly with the users of their PowerShell Gallery packages. Gli utenti danno la preferenza ai pacchetti che includono un sito di progetto, in quanto consente di ottenere informazioni più facilmente.Users prefer packages that provide this, as it allows them to get information about the package more easily. Molti pacchetti in PowerShell Gallery sono sviluppati in GitHub, altri sono resi disponibili da organizzazioni con una presenza Web dedicata.Many packages in the PowerShell Gallery are developed in GitHub, others are provided by organizations with a dedicated web presence. Entrambi gli ambienti possono essere considerati siti di progetto.Each of these can be considered a project site.

È possibile aggiungere un collegamento includendo ProjectURI nella sezione PSData del manifesto come indicato di seguito:Adding a link is done by including ProjectURI in the PSData section of the manifest as follows:

  # 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.When a ProjectURI is provided, the PowerShell Gallery will include a link to the Project Site on the left side of the package page.

Contrassegnare il pacchetto con PSEdition(s) e le piattaforme compatibiliTag your package with the compatible PSEdition(s) and platforms

Usare i tag seguenti per indicare agli utenti quali pacchetti funzioneranno con il loro ambiente:Use the following tags to demonstrate to users which packages will work well with their environment:

  • PSEdition_Desktop: i pacchetti compatibili con Windows PowerShellPSEdition_Desktop: Packages that are compatible with Windows PowerShell
  • PSEdition_Core: i pacchetti compatibili con PowerShell CorePSEdition_Core: Packages that are compatible with PowerShell Core
  • Windows: i pacchetti compatibili con il sistema operativo WindowsWindows: Packages that are compatible with the Windows Operating System
  • Linux: i pacchetti compatibili con i sistemi operativi LinuxLinux: Packages that are compatible with Linux Operating Systems
  • MacOS: i pacchetti compatibili con i sistemi operativi MacMacOS: Packages that are compatible with the Mac Operating System

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.By tagging your package with the compatible platform(s) it will be included in the Gallery search filters on the left pane of the search results. Se si ospita il pacchetto in GitHub, quando si contrassegna il pacchetto è anche possibile sfruttare le etichette di compatibilità di PowerShell Gallery esempio di etichetta di compatibilità.If you host your package on GitHub, when you tag your package, you can also take advantage of our PowerShell Gallery compatibility shields compatibility shield example.

Includere testInclude tests

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.Including tests with open-source code is important to users, as it gives them assurance about what you validate, and provides information on how your code works. Inoltre garantisce agli utenti la possibilità di adattare il codice al loro ambiente senza compromettere la funzionalità originale del codice stesso.It also allows users to ensure they don't break your original functionality if they modify your code to fit their environment.

È consigliabile creare test che supportano il framework di test Pester, sviluppato espressamente per PowerShell.It's strongly recommended that tests be written to take advantage of the Pester test framework, which has been designed specifically for PowerShell. Pester è disponibile in GitHub, in PowerShell Gallery ed è incluso in Windows 10, Windows Server 2016, WMF 5.0 e WMF 5.1.Pester is available in GitHub, the PowerShell Gallery, and ships in Windows 10, Windows Server 2016, WMF 5.0 and 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.The Pester project site in GitHub includes good documentation on writing Pester tests, from getting started to best practices.

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%.The targets for test coverage are called out in the High Quality Resource Module documentation, with 70% unit test code coverage recommended.

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.All packages published to the PowerShell Gallery must specify the license terms, or be bound by the license included in the Terms of Use under Exhibit A. The best approach to specifying a different license is to provide a link to the license using the LicenseURI in PSData. Per altre informazioni, vedere Manifesto dei pacchetti e interfaccia utente di Gallery.For more information, see Packages manifest and Gallery UI.

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 codiceSign your code

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.Code signing provides users with the highest level of assurance for who published the package, and that the copy of the code they acquire is exactly what the publisher released. Per altre informazioni generali sulla firma del codice, vedere Introduction to Code Signing (Introduzione alla firma del codice).To learn more about code signing generally, see Introduction to Code Signing. PowerShell supporta la convalida della firma del codice con due approcci principali:PowerShell supports validation of code signing through two primary approaches:

  • Firma dei file di scriptSigning script files
  • Firma di moduli mediante catalogoCatalog signing a module

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.Signing PowerShell files is a well-established approach to ensuring that the code being executed was produced by a reliable source, and hasn't been modified. Informazioni dettagliate sulla firma dei file di script di PowerShell sono disponibili nell'articolo About signing (Informazioni sulla firma).Details on how to sign PowerShell script files is covered in the About Signing article. Per riassumere, è possibile aggiungere una firma a qualsiasi file .PS1 convalidato da PowerShell quando viene caricato lo script.In overview, a signature can be added to any .PS1 file that PowerShell validates when the script is loaded. È possibile vincolare PowerShell all'uso di script firmati con i cmdlet dei criteri di esecuzione.PowerShell can be constrained using the Execution Policy cmdlets to ensure use of signed scripts.

La firma di moduli mediante catalogo è una funzionalità aggiunta in PowerShell 5.1.Catalog signing modules is a feature added to PowerShell in version 5.1. Le modalità per la firma di un modulo sono descritte nell'argomento Cmdlet di catalogo.How to sign a module is covered in the Catalog Cmdlets article. 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.In overview, catalog signing is done by creating a catalog file, which contains a hash value for every file in the module, and then signing that file.

I cmdlet di PowerShellGet Publish-Module, Install-Module e Update-Module verificano la validità della firma, quindi confermano che il valore hash di ogni pacchetto corrisponda a quello presente nel catalogo.The PowerShellGet Publish-Module, Install-Module, and Update-Module cmdlets will check the signature to ensure it's valid, then confirm that the hash value for each package matches what is in the catalog. Save-Module non convalida una firma.Save-Module doesn't validate a signature. 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.If a previous version of the module is installed on the system, Install-Module will confirm that the signing authority for the new version matches what was previously installed. Se il pacchetto non ha una firma tramite catalogo, Install-Module e Update-Module usano la firma in un file .PSD1.Install-Module and Update-Module will use the signature on a .PSD1 file if the package isn't catalog signed. La firma tramite catalogo può essere usata insieme alla firma dei file di script ma non la sostituisce.Catalog signing works with, but doesn't replace signing script files. PowerShell non convalida le firme del catalogo al caricamento del modulo.PowerShell doesn't validate catalog signatures at module load time.

Osservare le linee guida SemVer per il controllo delle versioniFollow SemVer guidelines for versioning

SemVer è una convenzione pubblica che descrive come strutturare e cambiare una versione per facilitare l'interpretazione delle modifiche.SemVer is a public convention that describes how to structure and change a version to allow easy interpretation of changes. La versione del pacchetto deve essere inclusa nei dati del manifesto.The version for your package must be included in the manifest data.

  • La versione deve essere strutturata con tre blocchi numerici separati da punti, ad esempio 0.1.1 o 4.11.192.The version should be structured as three numeric blocks separated by periods, as in 0.1.1 or 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.Versions starting with 0 indicate that the package isn't yet production ready, and the first number should only begin with 0 if that's the only number used.
  • La modifica del primo numero (da 1.9.9999 a 2.0.0) indica modifiche strutturali di primaria importanza da una versione alla successiva.Changes in the first number (1.9.9999 to 2.0.0) indicate major and breaking changes between the versions.
  • 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.Changes to the second number (1.1 to 1.2) indicate feature-level changes, such as adding new cmdlets to a module.
  • La modifica del terzo numero indica modifiche meno importanti, ad esempio l'aggiunta di nuovi parametri, esempi aggiornati o nuovi test.Changes to the third number indicate non-breaking changes, such as new parameters, updated samples, or new tests.
  • 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.When listing versions, PowerShell will sort the versions as strings, so 1.01.0 will be treated as greater than 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:PowerShell was created before SemVer was published, so it provides support for most but not all elements of SemVer, specifically:

  • Non supporta le stringhe di versione provvisoria nei numeri di versione.It doesn't support prerelease strings in version numbers. Questo è utile quando un autore vuole rilasciare una versione di anteprima di una nuova versione principale dopo aver rilasciato la versione 1.0.0.This is useful when a publisher wishes to deliver a preview release of a new major version after providing a version 1.0.0. Questa funzionalità verrà supportata in una versione futura dei cmdlet di PowerShell Gallery e PowerShellGet.This will be supported in a future release of the PowerShell Gallery and PowerShellGet cmdlets.
  • PowerShell e PowerShell Gallery supportano le stringhe di versione con 1, 2 e 4 segmenti.PowerShell and the PowerShell Gallery allow version strings with 1, 2, and 4 segments. 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.Many early modules did not follow the guidelines, and product releases from Microsoft include build information as a 4th block of numbers (for example 5.1.14393.1066). Dal punto di vista del controllo delle versioni, queste differenze vengono ignorate.From a versioning standpoint, these differences are ignored.

Eseguire test usando un repository localeTest using a local repository

PowerShell Gallery non è progettato per essere usato come destinazione per il testing del processo di pubblicazione.The PowerShell Gallery isn't designed to be a target for testing the publishing process. Il modo migliore per testare l'intero processo di pubblicazione in PowerShell Gallery prevede la configurazione e l'uso di un repository personale locale.The best way to test out the end-to-end process of publishing to the PowerShell Gallery is to set up and use your own local repository. Questa operazione può essere eseguita in svariati modi, ad esempio:This can be done in a few ways, including:

  • Configurare un'istanza locale di PowerShell Gallery usando il progetto di PS Gallery privato in GitHub.Set up a local PowerShell Gallery instance, using the PS Private Gallery project in GitHub. Questo progetto di anteprima consente di configurare un'istanza di PowerShell Gallery che è possibile controllare e usare per i test.This preview project will help you set up an instance of the PowerShell Gallery that you can control, and use for your tests.
  • Configurare un repository NuGet interno.Set up an internal Nuget repository. 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.This will require more work to set up, but will have the advantage of validating a few more of the requirements, notably validating use of an API key, and whether or not dependencies are present in the target when you publish.
  • Configurare una condivisione file come repository di test.Set up a file share as the test repository. Si tratta di una soluzione semplice da configurare, ma trattandosi di una condivisione file, le convalide indicate in precedenza non verranno eseguite.This is easy to set up, but since it's a file share, the validations noted above will not take place. 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.One potential advantage in this case is that the file share doesn't check the required API key, so you can use the same key you would use to publish to the 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.With any of these solutions, use Register-PSRepository to define a new repository , which you use in the -Repository parameter for 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.One additional point about test publishing: any package you publish to the PowerShell Gallery can't be deleted without help from the operations team, who will confirm that nothing is dependent upon the package you wish to publish. 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.For that reason, we don't support the PowerShell Gallery as a testing target, and will contact any publisher who does so.

Usare PowerShellGet per la pubblicazioneUse PowerShellGet to publish

È consigliabile che gli autori della pubblicazione usino i cmdlet Publish-Module e Publish-Script quando lavorano con PowerShell Gallery.It's strongly recommended that publishers use the Publish-Module and Publish-Script cmdlets when working with the PowerShell Gallery. PowerShellGet è stato creato per evitare che vengano memorizzate informazioni importanti sull'installazione da e la pubblicazione in PowerShell Gallery.PowerShellGet was created to help you avoid remembering important details about installing from and publishing to the 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.On occasion, publishers have chosen to skip PowerShellGet and use the NuGet client, or PackageManagement cmdlets, instead of Publish-Module. Molti dettagli vengono facilmente omessi, il che genera richieste di supporto di vario genere.There are a number of details that are easily missed, which results in a variety of support requests.

Se per qualsiasi motivo non è possibile usare Publish-Module o Publish-Script, inviare una notifica.If there's a reason that you can't use Publish-Module or Publish-Script, please let us know. Segnalare un problema nel repository GitHub di PowerShellGet e specificare i dettagli che determinano la scelta di NuGet o PackageManagement.File an issue in the PowerShellGet GitHub repo, and provide the details that cause you to choose NuGet or PackageManagement.

L'approccio più efficace per i pacchetti pubblicati in PowerShell Gallery è il seguente:The most successful approach we have found for packages published to the PowerShell Gallery is this:

  • Eseguire lo sviluppo iniziale in un sito di progetto open-source.Do initial development in an open-source project site. Il team di PowerShell usa GitHub.The PowerShell Team uses GitHub.
  • Usare i commenti e suggerimenti dei revisori e Powershell Script Analyzer per portare il codice a una condizione stabile.Use feedback from reviewers and Powershell Script Analyzer to get the code to stable state.
  • Includere documentazione, per comunicare agli altri utenti come usare il codice.Include documentation, so others know how to use your work.
  • Testare l'azione di pubblicazione usando un repository locale.Test out the publishing action using a local repository.
  • Pubblicare una versione stabile o alfa in PowerShell Gallery e includere la documentazione e il collegamento al sito del progetto.Publish a stable or Alpha release to the PowerShell Gallery, making sure to include the documentation and link to your project site.
  • Raccogliere il feedback e sviluppare il codice nel sito di progetto, quindi pubblicare gli aggiornamenti stabili in PowerShell Gallery.Gather feedback and iterate on the code in your project site, then publish stable updates to the PowerShell Gallery.
  • Aggiungere esempi e test Pester nel progetto e nel modulo.Add examples and Pester tests in your project and your module.
  • Decidere se firmare il codice del pacchetto.Decide if you want to code sign your package.
  • 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.When you feel the project is ready to use in a production environment, publish a 1.0.0 version to the PowerShell Gallery.
  • Continuare a raccogliere commenti e suggerimenti e sviluppare ulteriormente il codice in base all'input degli utenti.Continue to gather feedback and iterate on your code based on user input.