Compartilhar via

Diretrizes e práticas recomendadas de publicação do PowerShellGallery

  • Artigo

Este artigo descreve as etapas recomendadas usadas pelas equipes da Microsoft para garantir que os pacotes publicados na Galeria do PowerShell sejam amplamente adotados e forneçam alto valor aos usuários, com base em como a Galeria do PowerShell lida com dados de manifesto e em comentários de um grande número de usuários da Galeria do PowerShell. Os pacotes publicados seguindo essas diretrizes terão maior probabilidade de serem instalados, confiáveis e atrair mais usuários.

Incluem-se abaixo as diretrizes para o que faz um bom pacote da Galeria do PowerShell, quais configurações opcionais de Manifesto são mais importantes, aprimorando seu código com comentários de revisores iniciais e do Analisador de Scripts do Powershell, controle de versão do módulo, documentação, testes e exemplos de como usar o que você compartilhou. Grande parte desta documentação segue as diretrizes de publicação módulos de recursos DSC de alta qualidade.

Para obter a mecânica de publicar um pacote na Galeria do PowerShell, consulte Criando e publicando um pacote.

Comentários sobre essas diretrizes são bem-vindos. Se você tiver comentários, abra problemas em nosso repositório de documentação do GitHub.

Práticas recomendadas para publicar pacotes

As práticas recomendadas a seguir são o que os usuários dos itens da Galeria do PowerShell dizem ser importante e estão listadas em ordem de prioridade nominal. Pacotes que seguem essas diretrizes são muito mais propensos a serem baixados e adotados por outras pessoas.

  • Usar PSScriptAnalyzer
  • Incluir documentação e exemplos
  • Seja responsivo aos comentários
  • Fornecer módulos em vez de scripts
  • Fornecer links para um site de projeto
  • Marcar seu pacote com as plataformas e PSEdition compatíveis
  • Incluir testes com seus módulos
  • Incluir e/ou vincular aos termos de licença
  • Assinar seu código
  • Siga diretrizes de SemVer para controle de versão
  • Usar marcas comuns, conforme documentado em marcas comuns da Galeria do PowerShell
  • Testar a publicação usando um repositório local
  • Usar o PowerShellGet para publicar

Cada uma delas é abordada brevemente nas seções abaixo.

Usar PSScriptAnalyzer

PSScriptAnalyzer é uma ferramenta de análise de código estático gratuita que funciona no código do PowerShell. PSScriptAnalyzer identificará os problemas mais comuns vistos no código do PowerShell e, muitas vezes, uma recomendação de como corrigir o problema. A ferramenta é fácil de usar e categoriza os problemas como Erros (graves, devem ser resolvidos), Aviso (precisa ser revisado e deve ser resolvido) e Informações (vale a pena verificar as práticas recomendadas). Todos os pacotes publicados na Galeria do PowerShell serão verificados usando PSScriptAnalyzer e quaisquer erros serão relatados de volta ao proprietário e deverão ser resolvidos.

A melhor prática é executar Invoke-ScriptAnalyzer com aviso de -Recurse e -Severity.

Examine os resultados e verifique se:

  • Todos os erros são corrigidos ou resolvidos em sua documentação.
  • Todos os avisos são revisados e endereçados quando aplicável.

Os usuários que baixam pacotes da Galeria do PowerShell são altamente incentivados a executar PSScriptAnalyzer e avaliar todos os Erros e Avisos. É muito provável que os usuários entrem em contato com os proprietários do pacote se virem que há um erro relatado por PSScriptAnalyzer. Se houver um motivo convincente para o pacote manter o código sinalizado como um erro, adicione essas informações à sua documentação para evitar ter que responder à mesma pergunta muitas vezes.

Incluir documentação e exemplos

Documentação e exemplos são a melhor maneira de garantir que os usuários possam aproveitar qualquer código compartilhado.

A documentação é a coisa mais útil para incluir em pacotes publicados na Galeria do PowerShell. Os usuários geralmente ignorarão pacotes sem documentação, pois a alternativa é ler o código para entender o que é o pacote e como usá-lo. Há vários artigos disponíveis sobre como fornecer documentação com pacotes do PowerShell, incluindo:

  • As diretrizes para fornecer ajuda estão em Como escreverde Ajuda do Cmdlet.
  • Criar ajuda de cmdlet, que é a melhor abordagem para qualquer script, função ou cmdlet do PowerShell. Para obter informações sobre como criar ajuda de cmdlet, comece com How to Write Cmdlet Help. Para adicionar ajuda em um script, consulte Sobre a ajuda baseada em comentários.
  • Muitos módulos também incluem documentação no formato de texto, como arquivos MarkDown. Isso pode ser particularmente útil quando há um site de projeto no GitHub, onde Markdown é um formato muito usado. A melhor prática é usar markdown com sabor do GitHub.

Exemplos mostram aos usuários como o pacote deve ser usado. Muitos desenvolvedores dirão que analisam exemplos antes da documentação para entender como usar algo. Os melhores tipos de exemplos mostram o uso básico, além de um caso de uso realista simulado e o código é bem comentado. Exemplos de módulos publicados na Galeria do PowerShell devem estar em uma pasta Exemplos na raiz do módulo.

Um bom padrão para exemplos pode ser encontrado no módulo PSDscResource na pasta Examples\RegistryResource. Há quatro casos de uso de exemplo com uma breve descrição na parte superior de cada arquivo que documenta o que está sendo demonstrado.

Gerenciar dependências

É importante especificar módulos dos quais o módulo depende no Manifesto do Módulo. Isso permite que o usuário final não precise se preocupar com a instalação das versões adequadas dos módulos nos quais o seu depende. Para especificar módulos dependentes, você deve usar o campo de módulo necessário no manifesto do módulo. Isso carregará todos os módulos listados no ambiente global antes de importar o módulo, a menos que eles já tenham sido carregados. Por exemplo, alguns módulos já podem ser carregados por um módulo diferente. Também é possível especificar uma versão específica para carregar usando o campo RequiredVersion em vez do campo ModuleVersion. Ao usar ModuleVersion, ele carregará a versão mais recente disponível com um mínimo da versão especificada. Quando não estiver usando o campo RequiredVersion, para especificar uma versão específica, é importante monitorar as atualizações de versão para o módulo necessário. É especialmente importante estar ciente de quaisquer alterações interruptivas que possam afetar a experiência do usuário com seu módulo.

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"})

Responder aos comentários

Os proprietários de pacotes que respondem corretamente aos comentários são altamente valorizados pela comunidade. Os usuários que fornecem comentários construtivos são importantes para responder, pois estão interessados o suficiente no pacote para tentar ajudar a melhorá-lo.

Há um método de comentários disponível na Galeria do PowerShell:

  • Contate o Proprietário: isso permite que um usuário envie um email para o proprietário do pacote. Como proprietário do pacote, é importante monitorar o endereço de email usado com os pacotes da Galeria do PowerShell e responder a problemas gerados. A única desvantagem desse método é que somente o usuário e o proprietário verão a comunicação, portanto, o proprietário pode ter que responder à mesma pergunta muitas vezes.

Os proprietários que respondem aos comentários construtivamente são apreciados pela comunidade. Use a oportunidade no relatório para solicitar mais informações. Se necessário, forneça uma solução alternativa ou identifique se uma atualização corrige um problema.

Se houver um comportamento inadequado observado em qualquer um desses canais de comunicação, use o recurso De Abuso de Relatório da Galeria do PowerShell para entrar em contato com os Administradores da Galeria.

Módulos versus scripts

Compartilhar um script com outros usuários é ótimo e fornece a outras pessoas exemplos de como resolver problemas que eles podem ter. O problema é que os scripts na Galeria do PowerShell são arquivos únicos sem documentação, exemplos e testes separados.

Os Módulos do PowerShell têm uma estrutura de pastas que permite que várias pastas e arquivos sejam incluídos com o pacote. A estrutura do módulo permite incluir os outros pacotes que listamos como práticas recomendadas: ajuda de cmdlet, documentação, exemplos e testes. A maior desvantagem é que um script dentro de um módulo deve ser exposto e usado como uma função. Para obter informações sobre como criar um módulo, consulte Escrevendo um módulo do Windows PowerShell.

Há situações em que um script oferece uma experiência melhor para o usuário, especialmente com configurações de DSC. A prática recomendada para configurações de DSC é publicar a configuração como um script com um módulo que contém os documentos, exemplos e testes. O script lista o módulo que acompanha o RequiredModules = @(Name of the Module). Essa abordagem pode ser usada com qualquer script.

Scripts autônomos que seguem as outras práticas recomendadas fornecem valor real para outros usuários. Fornecer documentação baseada em comentários e um link para um Site do Projeto são altamente recomendados ao publicar um script na Galeria do PowerShell.

Um Site de Projeto é onde um editor pode interagir diretamente com os usuários de seus pacotes da Galeria do PowerShell. Os usuários preferem pacotes que fornecem isso, pois permite que eles obtenham informações sobre o pacote com mais facilidade. Muitos pacotes na Galeria do PowerShell são desenvolvidos no GitHub, outros são fornecidos por organizações com uma presença da Web dedicada. Cada um deles pode ser considerado um site de projeto.

A adição de um link é feita incluindo o ProjectURI na seção PSData do manifesto da seguinte maneira:

  # 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 pacote.

Marcar seu pacote com as plataformas e PSEdition compatíveis

Use as seguintes marcas para demonstrar aos usuários quais pacotes funcionarão bem com seu ambiente:

  • PSEdition_Desktop: pacotes compatíveis com o Windows PowerShell
  • PSEdition_Core: pacotes compatíveis com o PowerShell 6 e superior
  • Windows: Pacotes compatíveis com o Sistema Operacional Windows
  • Linux: pacotes compatíveis com sistemas operacionais Linux
  • MacOS: pacotes compatíveis com o Sistema Operacional Mac

Marcando seu pacote com as plataformas compatíveis, ele será incluído nos filtros de pesquisa da Galeria no painel esquerdo dos resultados da pesquisa. Se você hospedar seu pacote no GitHub, ao marcar seu pacote, também poderá aproveitar nossos escudos de compatibilidade da Galeria do PowerShellexemplo de escudo de compatibilidade.

Incluir testes

A inclusão de testes com código-fonte aberto é importante para os usuários, pois fornece garantia sobre o que você valida e fornece informações sobre como o código funciona. Ele também permite que os usuários garantam que eles não interrompa sua funcionalidade original se modificarem seu código para se ajustarem ao ambiente.

É altamente recomendável que os testes sejam gravados para aproveitar a estrutura de teste do Pester, que foi projetada especificamente para o PowerShell. O Pester está disponível no GitHub, noda Galeria do PowerShell e no Windows 10, Windows Server 2016, WMF 5.0 e WMF 5.1.

O site de projeto Pester no GitHub inclui uma boa documentação sobre como escrever testes do Pester, desde introdução às práticas recomendadas.

Os destinos para cobertura de teste são chamados na documentação do módulo de recursos de alta qualidade , com 70% cobertura de código de teste de unidade recomendada.

Todos os pacotes publicados na Galeria do PowerShell devem especificar os termos de licença ou ser associados pela licença incluída no Termos de Uso em Exibir um. A melhor abordagem para especificar uma licença diferente é fornecer um link para a licença usando o LicenseURI em PSData. Para obter mais informações, consulte o manifesto Pacotes e a interface do usuário da galeria.

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'

Assinar seu código

A assinatura de código fornece aos usuários o nível mais alto de garantia para quem publicou o pacote e que a cópia do código que eles adquirem é exatamente o que o editor liberou. Para saber mais sobre a assinatura de código em geral, consulte Introdução aode Assinatura de Código. O PowerShell dá suporte à validação da assinatura de código por meio de duas abordagens primárias:

  • Assinar arquivos de script
  • Catalogar assinando um módulo

A assinatura de arquivos do PowerShell é uma abordagem bem estabelecida para garantir que o código que está sendo executado seja produzido por uma fonte confiável e não tenha sido modificado. Detalhes sobre como assinar arquivos de script do PowerShell são abordados no artigo Sobre Assinatura. Em visão geral, uma assinatura pode ser adicionada a qualquer arquivo .PS1 validado pelo PowerShell quando o script é carregado. O PowerShell pode ser restringido usando os cmdlets da Política de Execução para garantir o uso de scripts assinados.

Os módulos de assinatura de catálogo são um recurso adicionado ao PowerShell na versão 5.1. Como assinar um módulo é abordado no artigo cmdlets do catálogo . Em visão geral, a assinatura de catálogo é feita criando um arquivo de catálogo, que contém um valor de hash para cada arquivo no módulo e, em seguida, assinando esse arquivo.

Os cmdlets PowerShellGetPublish-Module, Install-Modulee Update-Module verificarão a assinatura para garantir que ela seja válida e, em seguida, confirmarão que o valor de hash para cada pacote corresponde ao que está no catálogo. Save-Module não valida uma assinatura. Se uma versão anterior do módulo estiver instalada no sistema, Install-Module confirmará que a autoridade de assinatura da nova versão corresponde ao que foi instalado anteriormente. Install-Module e Update-Module usarão a assinatura em um arquivo .PSD1 se o pacote não for assinado pelo catálogo. A assinatura de catálogo funciona com, mas não substitui os arquivos de script de assinatura. O PowerShell não valida assinaturas de catálogo no tempo de carregamento do módulo.

Siga as diretrizes do SemVer para controle de versão

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. A versão do pacote deve ser incluída nos dados do manifesto.

  • A versão deve ser estruturada como três blocos numéricos separados por períodos, como em 0.1.1 ou 4.11.192.
  • Versões que começam com 0 indicam que o pacote ainda não está pronto para produção e o primeiro número só deve começar com 0 se esse for o único número usado.
  • As alterações no primeiro número (1.9.9999 para 2.0.0) indicam alterações importantes e significativas entre as versões.
  • Alterações no segundo número (1.1 para 1.2) indicam alterações no nível do recurso, como adicionar novos cmdlets a um módulo.
  • As alterações no terceiro número indicam alterações não interruptivas, como novos parâmetros, exemplos atualizados ou novos testes.
  • Ao listar versões, o PowerShell classificará as versões como cadeias de caracteres, portanto, 1.01.0 serão tratados como maiores que 1.001.0.

O PowerShell foi criado antes da publicação do SemVer, portanto, ele fornece suporte para a maioria, mas não todos os elementos do SemVer, especificamente:

  • Ele não dá suporte a cadeias de caracteres de pré-lançamento em números de versão. Isso é útil quando um editor deseja entregar uma versão prévia de uma nova versão principal depois de fornecer uma versão 1.0.0. Isso terá suporte em uma versão futura da Galeria do PowerShell e cmdlets do PowerShellGet.
  • O PowerShell e a Galeria do PowerShell permitem cadeias de caracteres de versão com 1, 2 e 4 segmentos. Muitos módulos iniciais não seguiram as diretrizes e as versões do produto da Microsoft incluem informações de build como um 4º bloco de números (por exemplo, 5.1.14393.1066). Do ponto de vista do controle de versão, essas diferenças são ignoradas.

Testar usando um repositório local

A Galeria do PowerShell não foi projetada para ser um destino para testar o processo de publicação. A melhor maneira de testar o processo de publicação de ponta a ponta na Galeria do PowerShell é configurar e usar seu próprio repositório local. Isso pode ser feito de algumas maneiras, incluindo:

  • Configure uma instância local da Galeria do PowerShell usando o projeto PS Private Gallery no GitHub. Este projeto de visualização ajudará você a configurar uma instância da Galeria do PowerShell que você pode controlar e usar para seus testes.
  • Configurar um repositório nuget interno. Isso exigirá mais trabalho para configurar, mas terá a vantagem de validar mais alguns dos requisitos, notadamente validando o uso de uma chave de API e se as dependências estão presentes ou não no destino quando você publica.
  • Configurar um compartilhamento de arquivo como odo repositório de de teste. Isso é fácil de configurar, mas como é um compartilhamento de arquivos, as validações indicadas acima não ocorrerão. Uma vantagem potencial nesse caso é que o compartilhamento de arquivos não verifica a chave de API necessária, portanto, você pode usar a mesma chave que usaria para publicar na Galeria do PowerShell.

Com qualquer uma dessas soluções, use Register-PSRepository para definir um novo de repositório, que você usa no parâmetro -Repository para Publish-Module.

Um ponto adicional sobre a publicação de teste: qualquer pacote publicado na Galeria do PowerShell não pode ser excluído sem a ajuda da equipe de operações, que confirmará que nada depende do pacote que você deseja publicar. Por esse motivo, não damos suporte à Galeria do PowerShell como um destino de teste e entraremos em contato com qualquer editor que faça isso.

Usar o PowerShellGet para publicar

É altamente recomendável que os editores usem os cmdlets Publish-Module e Publish-Script ao trabalhar com a Galeria do PowerShell. PowerShellGet foi criado para ajudá-lo a evitar lembrar detalhes importantes sobre como instalar e publicar na Galeria do PowerShell. Às vezes, os editores optaram por ignorar do PowerShellGet e usar o cliente NuGet ou cmdlets PackageManagement, em vez de Publish-Module. Há vários detalhes que são facilmente perdidos, o que resulta em uma variedade de solicitações de suporte.

Se houver uma razão pela qual você não pode usar Publish-Module ou Publish-Script, informe-nos. Registre um problema no repositório do PowerShellGet GitHub e forneça os detalhes que fazem com que você escolha do NuGet ou PackageManagement.

A abordagem mais bem-sucedida que encontramos para pacotes publicados na Galeria do PowerShell é a seguinte:

  • Faça o desenvolvimento inicial em um site de projeto de software livre. A equipe do PowerShell usa o GitHub.
  • Use comentários de revisores e do Analisador de Scripts do PowerShell para obter o código para o estado estável.
  • Inclua a documentação, para que outras pessoas saibam como usar seu trabalho.
  • Teste a ação de publicação usando um repositório local.
  • Publique uma versão estável ou Alfa na Galeria do PowerShell, certificando-se de incluir a documentação e o link para o site do projeto.
  • Reúna comentários e itera no código em seu site de projeto e, em seguida, publique atualizações estáveis na Galeria do PowerShell.
  • Adicione exemplos e testes do Pester em seu projeto e em seu módulo.
  • Decida se deseja assinar o pacote pelo código.
  • Quando você sentir que o projeto está pronto para ser usado em um ambiente de produção, publique uma versão 1.0.0 na Galeria do PowerShell.
  • Continue coletando comentários e iterar em seu código com base na entrada do usuário.