Diretrizes e práticas recomendadas da Galeria do PowerShellPowerShellGallery Publishing Guidelines and Best Practices

Este tópico descreve as etapas recomendadas usadas pelas equipes da Microsoft para garantir que os itens publicados na Galeria do PowerShell sejam amplamente adotados e forneçam um valor alto para os usuários, com base em como a Galeria do PowerShell lida com os dados de manifesto e nos comentários de um grande número de usuários da Galeria do PowerShell.This topic describes recommended steps used by Microsoft teams to ensure the items 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. Os itens que forem publicados seguindo essas diretrizes terão maior probabilidade de ser instalados, de ganhar confiança e de atrair mais usuários.Items that are published following these guidelines will be more likely to be installed, trusted, and attract more users.

Abaixo estão as diretrizes para que um item da Galeria do PowerShell seja o ideal, quais configurações opcionais de manifesto são mais importantes, melhorias do código com comentários de revisores inicias e do Powershell Script Analyzer, controle de versão de seu módulo, documentação, testes e exemplos de como usar o que você compartilhou.Included below are guidelines for what makes a good PowerShell Gallery item, what optional Manifest settings are most important, improving your code with feedback from initial reviewers and Powershell Script Analyzer, versioning your module, documentation, tests & examples for how to use what you have shared. Grande parte desta documentação segue as diretrizes para publicar High Quality DSC Resource Modules (Módulos de recurso de DSC de alta qualidade).Much of this documentation follows the guidelines for publishing High Quality DSC Resource Modules.

Para obter o mecanismo de publicação de um item na Galeria do PowerShell, consulte Criar e publicar um item.For the mechanics of publishing an item to the PowerShell Gallery, see Creating and Publishing an Item.

Comentários sobre essas diretrizes são boas-vindos.Feedback on these guidelines is welcomed. Se você tiver comentários, abra problemas no nosso Repositório de documentação do Github.If you do have feedback, please open issues in our Github documentation repository.

Práticas recomendadas para itens publicadosBest Practices for Published Items

As seguintes práticas recomendadas são o que os usuários de itens da Galeria do PowerShell dizem que é importante e são elas listadas em ordem de prioridade nominal.The following best practices are what the users of PowerShell Gallery items say is important, and are listed in nominal priority order. Os itens que seguem estas diretrizes têm uma probabilidade muito maior de ser baixados e adotados por outras pessoas.Items that follow these guidelines are far more likely to be downloaded and adopted by others.

  • Usar PSScriptAnalyzerUse PSScriptAnalyzer
  • Incluir a documentação e exemplosInclude documentation and examples
  • Seja receptivo aos comentáriosBe responsive to feedback
  • Fornecer módulos em vez de scriptsProvide modules rather than scripts
  • Seguir as diretrizes [SemVer] para controle de versãoFollow [SemVer] guidelines for versioning
  • Fornecer links para um site do projetoProvide links to a project site
  • Incluir testes com os módulosInclude tests with your modules
  • Incluir e/ou vincular aos termos de licençaInclude and/or link to license terms
  • Assinar o códigoSign your code
  • Use marcas comuns, conforme documentado em Marcas comuns da Galeria do PowerShellUse common tags, as documented in Common PowerShell Gallery tags

Cada uma delas é abordada brevemente nas seções a seguir.Each of these is covered briefly in the sections below.

Usar PSScriptAnalyzerUse PSScriptAnalyzer

O PSScriptAnalyzer é uma ferramenta de análise de código estático gratuita que funciona em códigos do PowerShell.PSScriptAnalyzer is a free static code analysis tool that works on PowerShell code. O PSScriptAnalyzer identificará os problemas mais comuns vistos no código do PowerShell e, geralmente, uma recomendação para corrigir o problema.PSScriptAnalyzer will identify the most common issues seen in PowerShell code, and often a recommendation for how to fix the issue. A ferramenta é fácil de usar e categoriza os problemas como Erros (graves, devem ser abordados), Avisos (precisam ser examinados e devem ser resolvidos) e Informações (vale a pena verificar visando as práticas recomendadas).The tool is easy to use, and categorizes the issues as Errors (severe, must be addressed), Warning (need to be reviewed & should be addressed), and Information (worth checking out for best practices). Todos os itens de itens publicados na Galeria do PowerShell serão examinados usando o PSScriptAnalyzer e todos os erros serão ser relatados para o proprietário e deverão ser abordados.All items item published to the PowerShell Gallery will be scanned using PSScriptAnalyzer, and any errors will be reported back to the owner and must be addressed.

A prática recomendada é executar Invoke-ScriptAnalyzer com Aviso -Recurse e -Severity.The best practice is to run Invoke-ScriptAnalyzer with -Recurse and -Severity Warning.

Examine os resultados e verifique se:Review the results, and ensure that:

  • Todos os erros foram corrigidos ou abordados na documentaçãoAll Errors are corrected or addressed in your documentation
  • Todos os avisos foram examinados e resolvidos quando aplicávelAll Warnings are reviewed, and addressed where applicable

Os usuários que adquirem itens da Galeria do PowerShell são altamente incentivados a executar PSScriptAnalyzer e s avaliar todos os Erros e Avisos.Users who acquire items from the PowerShell Gallery are strongly encouraged to run PSScriptAnalyzer and evaluate all Errors and Warnings. Os usuários têm maior probabilidade de entrar em contato com os proprietários do item quando percebem que um erro foi relatado pelo PSScriptAnalyzer.Users are very likely to contact item owners if they see that there is an error reported by PSScriptAnalyzer. Se houver um motivo convincente para o item manter o código sinalizado como um erro, adicione essas informações à documentação para evitar precisar responder à mesma pergunta muitas vezes.If there is a compelling reason for your item 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.

Incluir a documentação e exemplosInclude documentation and examples

Documentação e exemplos são a melhor maneira de garantir que os usuários possam aproveitar qualquer código compartilhado.Documentation and examples are the best way to ensure users can take advantage of any shared code.

A documentação é a coisa mais útil a ser incluída nos itens publicados na Galeria do PowerShell.Documentation is the most helpful thing to include in items published to the PowerShell Gallery. Os usuários geralmente ignoram itens sem a documentação, pois a alternativa é ler o código para entender o que é o item e como usá-lo.Users will generally bypass items without documentation, as the alternative is to read the code to understand what the item is and how to use it. Há vários artigos disponíveis no MSDN sobre como fornecer documentação com itens do PowerShell, incluindo:There are several articles available in MSDN on how to provide documentation with PowerShell items, including:

  • As diretrizes para fornecer ajuda estão em How to Write Cmdlet Help (Como escrever a ajuda do cmdlet)Guidelines for providing help are in How to Write Cmdlet Help
  • Criar a ajuda do cmdlet, que é a melhor abordagem para qualquer script, função ou cmdlet do PowerShell.Creating cmdlet help, which is the best approach for any PowerShell script, function, or cmdlet. Para obter informações de como criar a ajuda do cmdlet, inicie com How to Write Cmdlet Help (Como escrever a ajuda do cmdlet) na biblioteca MSDN (Microsoft Developer Network).For information about how to create cmdlet help, start with How to Write Cmdlet Help in the MSDN (Microsoft Developer Network) library. Para adicionar a ajuda dentro de um script, consulte About Comment Based Help (Sobre a ajuda baseada em comentários).To add help within a script, see About Comment Based Help.
  • Muitos módulos também incluem documentação no formato de texto, como arquivos de MarkDown.Many modules also include documentation in text format, such as MarkDown files. Isso pode ser particularmente útil quando há um site do projeto no Github, no qual o Markdown é um formato muito usado.This can be particularly helpful when there is a project site in Github, where Markdown is a heavily used format. A prática recomendada é usar Markdown para GithubThe best practice is to use Github-flavored Markdown

Exemplos mostram aos usuários como o item deve ser usado.Examples show users how the item is intended to be used. Muitos desenvolvedores dirão que eles consultam os exemplos antes da documentação para entender como usar algo.Many developers will say that they look at examples before documentation to understand how to use something. O melhor tipo de exemplo mostra o uso básico, além de um caso de uso realista simulado e o código é bem comentado.The best type of examples show basic use, plus a simulated realistic use case, and the code is well-commented. Os exemplos de módulos publicados na Galeria do PowerShell devem estar em uma pasta Exemplos na raiz do módulo.Examples for modules published to the PowerShell Gallery should be in an Examples folder under the module root.

Um bom padrão de exemplos pode ser encontrado no Módulo PSDscResource na pasta Examples\RegistryResource.A good pattern for examples can be found in the PSDscResource module under the Examples\RegistryResource folder. Há quatro exemplos de casos de uso com uma breve descrição na parte superior de cada arquivo que documenta o que está sendo demonstrado.There are four sample use cases with a brief description at the top of each file that documents what is being demonstrated.

Responder aos comentáriosRespond to feedback

Os proprietários de item que respondem corretamente aos comentários são altamente valorizados pela comunidade.Item owners who respond properly to feedback are highly valued by the community. É importante responder aos usuários que fornecem comentários construtivos, pois eles estão interessados no item o bastante para tentar ajudar a melhorá-lo.Users who provide constructive feedback are important to respond to, as they are interested enough in the item to try to help improve it.

Há dois métodos de comentários disponíveis na Galeria do PowerShell:There are two feedback methods available in the PowerShell Gallery:

  • Contatar proprietário: permite que um usuário envie um email para o proprietário do item.Contact Owner: This allows a user to send an email to the item owner(s). Como proprietário de um item, é importante monitorar o endereço de email usado com os itens da Galeria do PowerShell e responder aos problemas que surgirem.As an item owner, is important to monitor the email address used with the PowerShell Gallery items, and respond to issues that are raised. Uma desvantagem desse método é que apenas o usuário e o proprietário verão a comunicação, portanto, o proprietário poderá precisar responder à mesma pergunta várias vezes.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.
  • Comentários: Na parte inferior da página do item há um campo Comentário.Comments: At the bottom of the item page is a Comment field. A vantagem desse sistema é que outros usuários podem ver os comentários e as respostas, o que reduz o número de vezes que uma mesma pergunta deve ser respondida.The advantage to this system is that other users can see the comments and responses, which reduces the number of times any single question must be answered. Como proprietário de um item, é altamente recomendável que você Siga os comentários de cada item.As an item owner, it is strongly recommended that you Follow the comments made for each item. Consulte Fornecendo comentários por meio de mídia social ou do recurso Comentários para obter detalhes de como fazer isso.See Providing Feedback via Social Media or Comments for details on how to do that.

Os proprietários que respondem aos comentários de forma construtiva são apreciados pela comunidade.Owners who respond to feedback constructively are appreciated by the community. Use a oportunidade no relatório para solicitar mais informações, se necessário, fornecer uma solução alternativa ou identificar se uma atualização corrige um problema.Use the opportunity in the report to request more information if needed, provide a workaround, or identify if an update fixes a problem.

Se houver comportamento inadequado observado em algum desse canais de comunicação, use o recurso Relatar abuso da Galeria do PowerShell para contatar os administradores da galeria.If there is inappropriate behavior observed from either of these communication channels, use the Report Abuse feature of the PowerShell Gallery to contact the Gallery Administrators.

Módulos versus scriptsModules Versus Scripts

Compartilhar um script com outros usuários é ótimo e fornece aos outros alguns exemplos de como resolver os problemas que eles possam ter.Sharing a script with other users is great, and provides others with examples of how to solve problems they may have. O problema é que os scripts na Galeria do PowerShell são arquivos únicos sem documentação, testes e exemplos separados.The issue is that scripts in the PowerShell Gallery are single files without separate documentation, examples, and tests.

Os módulos do PowerShell têm uma estrutura de pasta que permite que várias pastas e arquivos sejam incluídos no pacote.PowerShell Modules have a folder structure that allows multiple folders and files to be included with the package. A estrutura do módulo permite incluir os outros itens listados como práticas recomendadas: ajuda do cmdlet, documentação, exemplos e testes.The module structure enables including the other items we list as best practices: cmdlet help, documentation, examples, and tests. A maior desvantagem é que um script dentro de um módulo deve ser exposto e usado como uma função.The biggest disadvantage is that a script inside a module must be exposed and used as a function. Para obter informações de como criar um módulo, consulte Writing a Windows PowerShell Module (Escrevendo um módulo do Windows PowerShell).For information on how to create a module, see Writing a Windows PowerShell Module.

Há situações em que um script fornece uma experiência melhor para o usuário, principalmente com configurações DSC.There are situations where a script provides a better experience for the user, particularly with DSC configurations. A prática recomendada para configurações DSC é publicar a configuração como um script com um módulo de acompanhamento que contenha documentos, exemplos e testes.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. O script lista o módulo de acompanhamento usando RequiredModules = @(Nome do módulo).The script lists the accompanying module using RequiredModules = @(Name of the Module). Essa abordagem pode ser usada com qualquer script.This approach can be used with any script.

Os scripts autônomos que seguem as práticas recomendadas fornecem um grande valor aos outros usuários.Standalone scripts that follow the other best practices provide real value to other users. Fornecer a documentação baseada em comentários e um link para um site do projeto são práticas altamente recomendadas ao publicar um script na Galeria do PowerShell.Providing comment-based documentation and a link to a Project Site are highly recommended when publishing a script to the PowerShell Gallery.

Um Site do projeto é onde um publicador pode interagir diretamente com os usuários de seus itens da Galeria do PowerShell.A Project Site is where a publisher can interact directly with the users of their PowerShell Gallery items. Os usuários preferem itens que fornecem um site, porque assim eles podem obter informações sobre o item com mais facilidade.Users prefer items that provide this, as it allows them to get information about the item more easily. Muitos itens na Galeria do PowerShell são desenvolvidos no GitHub, outros são oferecidos por organizações com uma presença na Web dedicada.Many items in the PowerShell Gallery are developed in GitHub, others are provided by organizations with a dedicated web presence. Cada um deles pode ser considerado um site do projeto.Each of these can be considered a project site.

A adição de um link é feita incluindo ProjectURI na seção PSData do manifesto da seguinte maneira: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 um ProjectURI for fornecido, a Galeria do PowerShell incluirá um link para o site do projeto no lado esquerdo da página do item.When a ProjectURI is provided, the PowerShell Gallery will include a link to the Project Site on the left side of the item page.

Incluir testesInclude tests

Incluir testes com código de software livre é importante para os usuários, porque isso oferece uma garantia sobre o que você valida e fornece informações sobre o funcionamento do código.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. Isso também permite que os usuários não prejudiquem a funcionalidade original caso modifiquem o seu código para ajustá-lo ao ambiente deles.It also allows users to ensure they do not break your original functionality if they modify your code to fit their environment.

É altamente recomendável que os testes sejam escritos para aproveitar a estrutura de testes do Pester, que foi projetada especificamente para o PowerShell.It is strongly recommended that tests be written to take advantage of the Pester test framework, which has been designed specifically for PowerShell. O Pester está disponível no GitHub, na Galeria do PowerShell e é fornecido no Windows 10, no Windows Server 2016, no WMF 5.0 e no 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.

O Site do projeto Pester no GitHub inclui uma boa documentação de como escrever testes Pester, desde a introdução até as práticas recomendadas.The Pester project site in GitHub includes good documentation on writing Pester tests, from getting started to best practices.

As metas de cobertura do teste são destacadas na Documentação do módulo do recurso de alta qualidade, com 70% de cobertura de código de teste de unidade recomendada.The targets for test coverage are called out in the High Quality Resource Module documentation, with 70% unit test code coverage recommended.

Assinar o códigoSign your code

A assinatura de código fornece aos usuários o nível mais alto de segurança sobre quem publicou o item e de garantia de que a cópia do código adquirido é exatamente o que o publicador lançou.Code signing provides users with the highest level of assurance for who published the item, and that the copy of the code they acquire is exactly what the publisher released. Para saber mais sobre assinatura de código em geral, consulte Introduction to Code Signing (Introdução à assinatura de código).To learn more about code signing generally, see Introduction to Code Signing. O PowerShell dá suporte à validação de assinatura de código por meio de duas abordagens principais:PowerShell supports validation of code signing through two primary approaches:

  • Assinando arquivos de scriptSigning script files
  • Assinado um módulo por catálogoCatalog signing a module

A assinatura de arquivos do PowerShell é uma abordagem bem estabelecida para garantir que o código que está sendo executado foi produzido por uma fonte confiável e não foi modificado.Signing PowerShell files is a well-established approach to ensuring that the code being executed was produced by a reliable source, and has not been modified. Os detalhes de como assinar arquivos de script do PowerShell são abordados no tópico Sobre assinatura.Details on how to sign PowerShell script files is covered in the About Signing topic. Em geral, uma assinatura pode ser adicionada a qualquer arquivo .PS1 que o PowerShell validar quando o script for carregado.In overview, a signature can be added to any .PS1 file that PowerShell validates when the script is loaded. O PowerShell pode ser restrito usando os cmdlets Política de execução para garantir o uso de scripts.PowerShell can be constrained using the Execution Policy cmdlets to ensure use of signed scripts. Esse recurso é usado frequentemente em ambientes altamente seguros.This feature is frequently used in highly secure environments.

A assinatura de catálogo de módulo é um recurso que foi adicionado no PowerShell na versão 5.1.Catalog signing modules is a feature added to PowerShell in version 5.1. Como assinar um módulo é abordado no tópico Cmdlets de catálogo.How to sign a module is covered in the Catalog Cmdlets topic. Em geral, a assinatura do catálogo é feita criando um arquivo de catálogo que contenha um valor de hash para cada arquivo no módulo e, em seguida, assinando esse arquivo.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. Os cmdlets publish-module, install-module, save-module e update-module do PowerShellGet verificarão a assinatura para garantir que ela seja válida e confirmarão se o valor de hash de cada item corresponde ao que está no catálogo.The PowerShellGet publish-module, install-module, save-module, and update-module cmdlets will check the signature to ensure it is valid, then confirm that the hash value for each item matches what is in the catalog. Se uma versão anterior do módulo estiver instalada no sistema, install-module confirmará se autoridade de assinatura da nova versão coincide com a que já estava instalada.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. A assinatura de catálogo funciona com os arquivos de script de assinatura, mas não os substitui.Catalog signing works with, but does not replace signing script files. O PowerShell não valida as assinaturas de catálogo no tempo de carregamento do módulo.PowerShell does not validate catalog signatures at module load time.

Seguir as diretrizes [SemVer] para controle de versãoFollow [SemVer] guidelines for versioning

SemVer é uma convenção pública que descreve como estruturar e alterar uma versão para permitir uma interpretação fácil das alterações.SemVer is a public convention that describes how to structure and change a version to allow easy intepretation of changes. A versão do item deve ser incluída nos dados de manifesto.The version for your item must be included in the manifest data.

  • A versão deve ser estruturada como 3 blocos numéricos separados por pontos, como em 0.1.1 ou 4.11.192The version should be structured as 3 numeric blocks separated by periods, as in 0.1.1 or 4.11.192
  • Versões que começam com "0" indicam que o item ainda não está preparado para produção e o primeiro número somente deverá começar com "0" se esse for o único número usadoVersions starting with "0" indicate that the item is not yet production ready, and the first number should only begin with "0" if that is the only number used
  • As alterações no primeiro número (1.9.9999 para 2.0.0) indicam alterações impactantes e recentes entre as versõesChanges in the first number (1.9.9999 to 2.0.0) indicate major and breaking changes between the versions
  • As alterações no segundo número (1.01 para 1.02) indicam alterações em nível de recurso, como a adição de novos cmdlets em um móduloChanges to the second number (1.01 to 1.02) indicate feature-level changes, such as adding new cmdlets to a module
  • As alterações no terceiro número indicam alterações não impactantes, como novos parâmetros, exemplos atualizados ou novos testesChanges to the third number indicate non-breaking changes, such as new parameters, updated samples, or new tests
  • Ao listar versões, o PowerShell as classificará como cadeias de caracteres de modo que 1.01.0 seja tratado como maior que 1.001.0When listing versions, PowerShell will sort the versions as strings, so 1.01.0 will be treated as greater than 1.001.0

O PowerShell foi criado antes da publicação do SemVer, portanto ele dá suporte para muitos elementos do SemVer, mas não para todos, especificamente:PowerShell was created before SemVer was published, so it provides support for most but not all elements of SemVer, specifically:

  • Ele não dá suporte para cadeias de caracteres de pré-versão em números de versão.It does not support prerelease strings in version numbers. Isso é útil quando um publicador deseja fornecer uma versão prévia de uma nova versão principal depois de fornecer uma versão 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. Isso terá suporte em uma versão futura da Galeria do PowerShell e dos cmdlets PowerShellGet.This will be supported in a future release of the PowerShell Gallery and PowerShellGet cmdlets.
  • O PowerShell e a Galeria do PowerShell permitem cadeias de caracteres de versão com 1, 2 e 4 segmentos.PowerShell and the PowerShell Gallery allow version strings with 1, 2, and 4 segments. Muitos módulos anteriores não seguiram as diretrizes e as versões de produto da Microsoft incluem as informações de build como um 4º bloco de números (por exemplo, 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). Do ponto de vista do controle de versão, essas diferenças são ignoradas.From a versioning standpoint, these differences are ignored.

Todos os itens publicados na Galeria do PowerShell devem especificar os termos de licença ou estarem associados à licença incluída nos Termos de uso na "Exibição A".All items 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". A melhor abordagem para especificar uma licença diferente é fornecer um link para a licença usando o LicenseURI em PSData.The best approach to specifying a different license is to provide a link to the license using the LicenseURI in PSData. Você pode encontrar um exemplo no tópico Campos de manifesto recomendados.You can find an example in the Recommended Manifest Fields topic.

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'

A abordagem mais bem-sucedida que encontramos para itens publicados na Galeria do PowerShell é a seguinte:The most successful approach we have found for items published to the PowerShell Gallery is this:

  • Faça o desenvolvimento inicial em um site de projeto de software livre.Do initial development in a an open-source project site. A equipe do PowerShell usa o Github.The PowerShell Team uses Github.
  • Use comentários de revisores e do Powershell Script Analyzer para levar o código ao estado estávelUse feedback from reviewers and Powershell Script Analyzer to get the code to stable state
  • Inclua a documentação, para que outras pessoas saibam como usar o seu trabalhoInclude documentation, so others know how to use your work
  • Publique uma versão estável ou Alfa na Galeria do PowerShell, lembrando-se de incluir a documentação e o link para o site do projetoPublish a stable or Alpha release to the PowerShell Gallery, making sure to include the documentation and link to your project site
  • Colete comentários, itere o código no site do projeto e, em seguida, publique atualizações estáveis na Galeria do PowerShellGather feedback and iterate on the code in your project site, then publish stable updates to the PowerShell Gallery
  • Adicione exemplos e testes do Pester no projeto e no móduloAdd examples and Pester tests in your project and your module
  • Decida se deseja assinar o código do seu itemDecide if you want to code sign your item
  • Quando você achar que o projeto está pronto para ser usado em um ambiente de produção, publique uma versão 1.0.0 na Galeria do PowerShellWhen you feel the project is ready to use in a production environment, publish a 1.0.0 version to the PowerShell Gallery
  • Continue a coletar comentários e itere em seu código com base nas informações fornecidas pelos usuáriosContinue to gather feedback and iterate on your code based on user input