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 nos 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 atrairem mais usuários.

Abaixo estão incluídas diretrizes sobre o que torna um bom pacote da Galeria do PowerShell, quais configurações opcionais de Manifesto são mais importantes, melhorando seu código com comentários dos revisores iniciais e Powershell Script Analyzer, 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 para publicar módulos de recursos DSC de alta qualidade.

Para obter a mecânica de publicação de um pacote na Galeria do PowerShell, consulte Criando e publicando um pacote.

As observações sobre estas orientações são bem-vindas. Se você tiver comentários, abra problemas em nosso repositório de documentação do GitHub .

Práticas recomendadas para publicação de 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. Os pacotes que seguem essas diretrizes têm muito mais probabilidade de serem baixados e adotados por outras pessoas.

  • Usar PSScriptAnalyzer
  • Inclua documentação e exemplos
  • Seja responsivo ao feedback
  • Fornecer módulos em vez de scripts
  • Fornecer links para um site de projeto
  • Marque seu pacote com o(s) PSEdition(s) compatível(is) e plataformas
  • Inclua testes com seus módulos
  • Incluir e/ou vincular aos termos de licença
  • Assine o seu código
  • Siga diretrizes do SemVer para controle de versão
  • Usar tags comuns, conforme documentado em Marcas comuns da Galeria do PowerShell
  • Testar a publicação usando um repositório local
  • Usar PowerShellGet para publicar

Cada um deles é abordado brevemente nas seções abaixo.

Usar PSScriptAnalyzer

PSScriptAnalyzer é uma ferramenta gratuita de análise de código estático 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 (precisam ser revisados e devem ser abordados) e Informações (vale a pena conferir as melhores práticas). Todos os pacotes publicados na Galeria do PowerShell serão verificados usando PSScriptAnalyzere quaisquer erros serão relatados ao proprietário e deverão ser resolvidos.

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

Analise os resultados e certifique-se de que:

  • Todos os erros são corrigidos ou abordados na sua documentação.
  • Todos os Avisos são revistos e abordados quando aplicável.

Os usuários que baixam pacotes da Galeria do PowerShell são altamente recomendados a executar PSScriptAnalyzer e avaliar todos os erros e avisos. É muito provável que os usuários entrem em contato com os proprietários de pacotes se virem que há um erro relatado pelo 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.

Inclua documentação e exemplos

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

A documentação é a coisa mais útil a ser incluída em pacotes publicados na Galeria do PowerShell. Os usuários geralmente ignoram 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 How to Write Cmdlet Help.
  • Criando ajuda de cmdlet, que é a melhor abordagem para qualquer script, função ou cmdlet do PowerShell. Para obter informações sobre como criar ajuda para cmdlets, comece com de Ajuda do cmdlet Como escrever . Para adicionar ajuda a um script, consulte Sobre a Ajuda Baseada em Comentários.
  • Muitos módulos também incluem documentação em 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 de GitHub.

Os exemplos mostram aos usuários como o pacote deve ser usado. Muitos desenvolvedores dirão que olham para 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. Os 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 exemplos de casos de uso com uma breve descrição na parte superior de cada arquivo que documenta o que está sendo demonstrado.

Gerenciar dependências

É importante especificar os módulos dos quais o módulo depende no Manifesto do módulo. Isso permite que o usuário final não tenha que se preocupar em instalar as versões adequadas dos módulos dos quais o seu depende. Para especificar módulos dependentes, você deve usar o campo de módulo obrigató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 significativas 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 adequadamente ao feedback são altamente valorizados pela comunidade. Os usuários que fornecem feedback construtivo são importantes para responder, pois estão interessados o suficiente no pacote para tentar ajudar a melhorá-lo.

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

  • Contato com o proprietário: Isso permite que um usuário envie um e-mail para o proprietário do pacote. Como proprietário de um pacote, é importante monitorar o endereço de email usado com os pacotes da Galeria do PowerShell e responder aos problemas levantados. A única desvantagem para este método é que apenas o usuário e proprietário nunca verá a comunicação, então o proprietário pode ter que responder à mesma pergunta muitas vezes.

Os proprietários que respondem ao feedback de forma construtiva são apreciados pela comunidade. Aproveite 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 Denunciar Abuso 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 aos outros exemplos de como resolver problemas que possam 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 no pacote. A estrutura do módulo permite incluir os outros pacotes que listamos como práticas recomendadas: ajuda do 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 fornece uma melhor experiência para o usuário, particularmente com configurações DSC. A prática recomendada para configurações 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 o acompanha usando 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 de 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 forneçam isso, pois isso lhes permite obter informações sobre o pacote mais facilmente. Muitos pacotes na Galeria do PowerShell são desenvolvidos no GitHub, outros são fornecidos por organizações com uma presença dedicada na Web. Cada um deles pode ser considerado um local de projeto.

A adição de um link é feita incluindo 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 é fornecido, a Galeria do PowerShell incluirá um link para o Site do Projeto no lado esquerdo da página do pacote.

Marque seu pacote com o(s) PSEdition(s) compatível(is) e plataformas

Use as seguintes tags 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

Ao marcar o seu pacote com a(s) plataforma(s) compatível(is), 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 PowerShell exemplo de escudo de compatibilidade.

Incluir testes

Incluir testes com código aberto é importante para os usuários, pois dá a eles garantia sobre o que você valida e fornece informações sobre como seu código funciona. Ele também permite que os usuários garantam que não quebrem sua funcionalidade original se modificarem seu código para se adequar ao ambiente.

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

O site do projeto Pester no GitHub inclui boa documentação sobre como escrever testes Pester, desde os primeiros passos até as melhores práticas.

As metas para cobertura de teste são descritas na documentação do High Quality Resource Module, com 70% cobertura de código de teste unitário recomendada.

Todos os pacotes publicados na Galeria do PowerShell devem especificar os termos de licença ou estar vinculados à licença incluída no de Termos de Uso do sob Anexo A. 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 Packages manifest e 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'

Assine o seu código

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

  • Assinando arquivos de script
  • Assinatura de catálogo de um módulo

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. Os detalhes sobre como assinar arquivos de script do PowerShell são abordados no artigo Sobre a assinatura. Na visão geral, uma assinatura pode ser adicionada a qualquer arquivo de .PS1 que o PowerShell valida quando o script é carregado. O PowerShell pode ser restringido usando os cmdlets 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. Na 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 se 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á se a autoridade de assinatura para a nova versão corresponde ao que foi instalado anteriormente. Install-Module e Update-Module usarão a assinatura em um arquivo de .PSD1 se o pacote não estiver assinado por catálogo. A assinatura de catálogo funciona com, mas não substitui a assinatura de arquivos de script. 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 seu pacote deve ser incluída nos dados do manifesto.

  • A versão deve ser estruturada em três blocos numéricos separados por pontos, como em 0.1.1 ou 4.11.192.
  • As 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.
  • Alterações no primeiro número (1.9.9999 a 2.0.0) indicam mudanças importantes e significativas entre as versões.
  • As alterações no segundo número (1.1 para 1.2) indicam alterações no nível do recurso, como a adição de novos cmdlets a um módulo.
  • As alterações no terceiro número indicam alterações ininterruptas, como novos parâmetros, amostras atualizadas ou novos testes.
  • Ao listar versões, o PowerShell classificará as versões como cadeias de caracteres, para que 1.01.0 sejam tratadas como maiores que 1.001.0.

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

  • Ele não suporta strings 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 PowerShellGet.
  • O PowerShell e a Galeria do PowerShell permitem cadeias de caracteres de versão com 1, 2 e 4 segmentos. Muitos dos primeiros módulos não seguiam as diretrizes, e as versões de produtos da Microsoft incluem informações de compilação 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.

Teste 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 completo de publicação 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.
  • Configure um repositório interno do Nuget . Isso exigirá mais trabalho para configurar, mas terá a vantagem de validar mais alguns dos requisitos, principalmente validando o uso de uma chave de API e se as dependências estão ou não presentes no destino quando você publica.
  • Configure um compartilhamento de arquivos como o repositório de de teste. Isso é fácil de configurar, mas como é um compartilhamento de arquivos, as validações mencionadas 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 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 oferecemos suporte à Galeria do PowerShell como destino de teste e entraremos em contato com qualquer editor que fizer isso.

Usar 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 a instalação e publicação na Galeria do PowerShell. Ocasionalmente, os editores optaram por ignorar PowerShellGet e usar o cliente NuGet ou cmdlets do PackageManagement, em vez de Publish-Module. Há uma série de detalhes que são facilmente perdidos, o que resulta em uma variedade de solicitações de suporte.

Se houver um motivo pelo qual você não pode usar Publish-Module ou Publish-Script, entre em contato conosco. Registre um problema no repositório PowerShellGet GitHub e forneça os detalhes que fazem com que você escolha NuGet ou PackageManagement.

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

  • Faça o desenvolvimento inicial em um site de projeto de código aberto. A equipe do PowerShell usa o GitHub.
  • Use os comentários dos revisores e do PowerShell Script Analyzer para colocar o código no estado estável.
  • Inclua documentação, para que outros saibam como usar o seu trabalho.
  • Teste a ação de publicação usando um repositório local.
  • Publique uma versão estável ou Alpha na Galeria do PowerShell, certificando-se de incluir a documentação e o link para o site do projeto.
  • Reúna comentários e itere o código em seu site de projeto e, em seguida, publique atualizações estáveis na Galeria do PowerShell.
  • Adicione exemplos e testes Pester no seu projeto e no seu módulo.
  • Decida se deseja assinar o código do seu pacote.
  • Quando achar que o projeto está pronto para uso em um ambiente de produção, publique uma versão 1.0.0 na Galeria do PowerShell.
  • Continue a coletar comentários e iterar seu código com base na entrada do usuário.