Diretrizes e Melhores Práticas de Publicação do PowerShellGallery

Artigo
06/27/2023

Este artigo descreve os passos recomendados utilizados pelas equipas da Microsoft para garantir que os pacotes publicados no Galeria do PowerShell serão amplamente adotados e fornecem um valor elevado aos utilizadores, com base na forma como o Galeria do PowerShell processa os dados de manifesto e nos comentários de um grande número de utilizadores Galeria do PowerShell. Os pacotes publicados ao seguir estas diretrizes serão mais propensos a serem instalados, fidedignos e a atrair mais utilizadores.

Abaixo estão incluídas diretrizes para o que torna um bom pacote de Galeria do PowerShell, quais as definições de Manifesto opcionais mais importantes, melhorando o seu código com comentários de revisores iniciais e do Analisador de Scripts do Powershell, controlo de versões do módulo, documentação, testes e exemplos sobre como utilizar o que partilhou. Grande parte desta documentação segue as diretrizes para publicar Módulos de Recursos DSC de Alta Qualidade.

Para obter a mecânica da publicação de um pacote no Galeria do PowerShell, veja Criar e Publicar um Pacote.

O feedback sobre estas diretrizes é bem-vindo. Se tiver comentários, abra problemas no nosso repositório de documentação do GitHub.

Melhores práticas para publicar pacotes

As seguintes melhores práticas são o que os utilizadores de Galeria do PowerShell itens dizem ser importante e estão listados por ordem de prioridade nominal. Os pacotes que seguem estas diretrizes são muito mais propensos a serem transferidos e adotados por outras pessoas.

Utilizar o PSScriptAnalyzer
Incluir documentação e exemplos
Responder a comentários
Fornecer módulos em vez de scripts
Fornecer ligações para um site de projeto
Etiquetar o seu pacote com pSEdition(s) compatíveis e plataformas
Incluir testes com os módulos
Incluir e/ou ligar aos termos de licença
Assinar o código
Siga as diretrizes do SemVer para controlo de versões
Utilizar etiquetas comuns, conforme documentado em Etiquetas de Galeria do PowerShell Comuns
Testar a publicação com um repositório local
Utilizar o PowerShellGet para publicar

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

Utilizar o PSScriptAnalyzer

O PSScriptAnalyzer é uma ferramenta de análise de código estático gratuita que funciona no código do PowerShell. O PSScriptAnalyzer identificará os problemas mais comuns vistos no código do PowerShell e, muitas vezes, uma recomendação sobre como corrigir o problema. A ferramenta é fácil de utilizar e categoriza os problemas como Erros (grave, têm de ser resolvidos), Aviso (tem de ser revisto e deve ser resolvido) e Informações (vale a pena verificar as melhores práticas). Todos os pacotes publicados no Galeria do PowerShell serão analisados através do PSScriptAnalyzer e quaisquer erros serão comunicados ao proprietário e terão de ser resolvidos.

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

Reveja 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 sempre que aplicável.

Os utilizadores que transferem pacotes do Galeria do PowerShell são fortemente encorajados a executar o PSScriptAnalyzer e a avaliar todos os Erros e Avisos. É muito provável que os utilizadores contactem os proprietários dos pacotes se virem que existe um erro comunicado pelo PSScriptAnalyzer. Se existir um motivo apelativo para o pacote manter o código sinalizado como um erro, adicione essas informações à sua documentação para evitar ter de responder muitas vezes à mesma pergunta.

Incluir documentação e exemplos

A documentação e os exemplos são a melhor forma de garantir que os utilizadores podem tirar partido de qualquer código partilhado.

A documentação é a coisa mais útil a incluir nos pacotes publicados no Galeria do PowerShell. Geralmente, os utilizadores ignoram os pacotes sem documentação, uma vez que a alternativa é ler o código para compreender o que é o pacote e como utilizá-lo. Existem vários artigos disponíveis sobre como fornecer documentação com pacotes do PowerShell, incluindo:

As diretrizes para fornecer ajuda estão em Como Escrever a Ajuda do Cmdlet.
Criar ajuda de cmdlets, 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 a Ajuda do Cmdlet How to Write. Para adicionar ajuda num script, consulte Acerca da Ajuda Baseada em Comentários.
Muitos módulos também incluem documentação no formato de texto, como ficheiros MarkDown. Isto pode ser particularmente útil quando existe um site de projeto no GitHub, onde o Markdown é um formato muito utilizado. A melhor prática é utilizar o Markdown com sabor ao GitHub.

Os exemplos mostram aos utilizadores como o pacote se destina a ser utilizado. Muitos programadores dirão que analisam exemplos antes da documentação para compreender como utilizar algo. Os melhores tipos de exemplos mostram a utilização básica, além de um caso de utilização realista simulado e o código é bem comentado. Os exemplos de módulos publicados no Galeria do PowerShell devem estar numa pasta Exemplos na raiz do módulo.

Pode encontrar um bom padrão para exemplos no módulo PSDscResource na Examples\RegistryResource pasta. Existem quatro casos de utilização de exemplo com uma breve descrição na parte superior de cada ficheiro que documenta o que está a ser demonstrado.

Gerir Dependências

É importante especificar os módulos de que o módulo depende no Manifesto do Módulo. Isto permite que o utilizador final não tenha de se preocupar com a instalação das versões adequadas dos módulos em que os seus assumem uma dependência. Para especificar módulos dependentes, deve utilizar o campo de módulo necessário no manifesto do módulo. Esta ação irá carregar todos os módulos listados para o ambiente global antes de importar o módulo, a menos que já tenham sido carregados. Por exemplo, alguns módulos podem já estar carregados por um módulo diferente. Também é possível especificar uma versão específica para carregar com o campo RequiredVersion em vez do campo ModuleVersion . Ao utilizar ModuleVersion, irá carregar a versão mais recente disponível com um mínimo da versão especificada. Quando não estiver a utilizar o campo RequiredVersion , para especificar uma versão específica, é importante monitorizar 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 utilizador com o 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 a comentários

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

Existe um método de feedback disponível no Galeria do PowerShell:

Proprietário do Contacto: isto permite que um utilizador envie um e-mail para o proprietário do pacote. Como proprietário de um pacote, é importante monitorizar o endereço de e-mail utilizado com os pacotes de Galeria do PowerShell e responder a problemas que são gerados. A única desvantagem deste método é que apenas o utilizador e o proprietário verão a comunicação, pelo que o proprietário poderá ter de responder à mesma pergunta muitas vezes.

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

Se existir um comportamento inadequado observado em qualquer um destes canais de comunicação, utilize a funcionalidade Report Abuse do Galeria do PowerShell para contactar os Administradores da Galeria.

Módulos Versus Scripts

Partilhar um script com outros utilizadores é ótimo e fornece a outras pessoas exemplos de como resolver problemas que possam ter. O problema é que os scripts no Galeria do PowerShell são ficheiros únicos sem documentação, exemplos e testes separados.

Os Módulos do PowerShell têm uma estrutura de pastas que permite a inclusão de várias pastas e ficheiros com o pacote. A estrutura do módulo permite incluir os outros pacotes que listamos como melhores práticas: ajuda do cmdlet, documentação, exemplos e testes. A maior desvantagem é que um script dentro de um módulo tem de ser exposto e utilizado como uma função. Para obter informações sobre como criar um módulo, veja Writing a Windows PowerShell Module (Escrever um Módulo Windows PowerShell).

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

Os scripts autónomos que seguem as outras melhores práticas fornecem valor real a outros utilizadores. Ao publicar um script no Galeria do PowerShell, recomendamos vivamente que forneça documentação baseada em comentários e uma ligação para um Site de Projeto.

Fornecer uma ligação para um site de projeto

Um Site de Projeto é onde um publicador pode interagir diretamente com os utilizadores dos pacotes de Galeria do PowerShell. Os utilizadores preferem pacotes que o forneçam, uma vez que lhes permite obter informações sobre o pacote mais facilmente. Muitos pacotes no Galeria do PowerShell são desenvolvidos no GitHub, outros são fornecidos por organizações com uma presença Web dedicada. Cada um destes pode ser considerado um site de projeto.

A adição de uma ligação é feita ao incluir o ProjectURI na secção PSData do manifesto da seguinte forma:

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

Quando um ProjectURI é fornecido, o Galeria do PowerShell incluirá uma ligação para o Site do Projeto no lado esquerdo da página do pacote.

Etiquetar o seu pacote com pSEdition(s) compatíveis e plataformas

Utilize as seguintes etiquetas para demonstrar aos utilizadores quais os pacotes que funcionarão bem com o respetivo ambiente:

PSEdition_Desktop: Pacotes compatíveis com Windows PowerShell
PSEdition_Core: Pacotes compatíveis com o PowerShell 6 e superior
Windows: Pacotes compatíveis com o Sistema Operativo Windows
Linux: Pacotes compatíveis com Sistemas Operativos Linux
MacOS: Pacotes compatíveis com o Sistema Operativo Mac

Ao etiquetar o pacote com as plataformas compatíveis, este será incluído nos filtros de pesquisa galeria no painel esquerdo dos resultados da pesquisa. Se alojar o seu pacote no GitHub, ao marcar o seu pacote, também pode tirar partido do nosso exemplo de escudo de compatibilidade de escudos de compatibilidade Galeria do PowerShell.

Incluir testes

A inclusão de testes com código open-source é importante para os utilizadores, uma vez que lhes dá garantias sobre o que valida e fornece informações sobre como o seu código funciona. Também permite que os utilizadores garantam que não quebram a funcionalidade original se modificarem o seu código para se adaptarem ao seu ambiente.

Recomenda-se vivamente que os testes sejam escritos para tirar partido da arquitetura de teste pester, que foi concebida especificamente para o PowerShell. O Pester está disponível no GitHub, no Galeria do PowerShell e é fornecido em 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 pester, desde começar às melhores práticas.

Os destinos para cobertura de teste são destacados na documentação do Módulo de Recursos de Alta Qualidade, com 70% de cobertura de código de teste de unidade recomendada.

Incluir e/ou ligar aos termos de licença

Todos os pacotes publicados no Galeria do PowerShell têm de especificar os termos de licenciamento ou estar vinculados pela licença incluída nos Termos de Utilização em Prova A. A melhor abordagem para especificar uma licença diferente é fornecer uma ligação para a licença com o LicenseURI no PSData. Para obter mais informações, veja Manifesto de pacotes e IU 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 o código

A assinatura de código fornece aos utilizadores o nível mais elevado de garantia para quem publicou o pacote e que a cópia do código que adquirem é exatamente o que o publicador lançou. Para saber mais sobre a assinatura de código em geral, veja Introdução à Assinatura de Código. O PowerShell suporta a validação da assinatura de código através de duas abordagens primárias:

Assinar ficheiros de script
Catálogo a assinar um módulo

Assinar ficheiros do PowerShell é uma abordagem bem estabelecida para garantir que o código que está a ser executado foi produzido por uma origem fiável e não foi modificado. Os detalhes sobre como assinar ficheiros de script do PowerShell são abordados no artigo Sobre a Assinatura . Em descrição geral, uma assinatura pode ser adicionada a qualquer .PS1 ficheiro que o PowerShell valide quando o script é carregado. O PowerShell pode ser restringido através dos cmdlets da Política de Execução para garantir a utilização de scripts assinados.

Os módulos de assinatura de catálogo são uma funcionalidade adicionada ao PowerShell na versão 5.1. Como assinar um módulo é abordado no artigo Cmdlets do Catálogo . Em visão geral, a sessão de autógrafos do catálogo é feita através da criação de um ficheiro de catálogo, que contém um valor de hash para cada ficheiro do módulo e, em seguida, assinando esse ficheiro.

Os cmdlets powerShellGetPublish-Module, Install-Modulee e Update-Module verificarão a assinatura para garantir que é válida e, em seguida, confirmarão que o valor hash de 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 utilizará a assinatura num .PSD1 ficheiro se o pacote não estiver assinado no catálogo. A assinatura do catálogo funciona com, mas não substitui a assinatura de ficheiros de script. O PowerShell não valida assinaturas de catálogo no tempo de carregamento do módulo.

Siga as diretrizes do SemVer para controlo de versões

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 tem de 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.
As versões que começam por 0 indicar que o pacote ainda não está pronto para produção e que o primeiro número só deve começar 0 se for o único número utilizado.
As alterações no primeiro número (1.9.9999 para 2.0.0) indicam alterações principais e interruptivas entre as versões.
As alterações ao segundo número (1.1 para ) indicam alterações ao 1.2nível da funcionalidade, como adicionar novos cmdlets a um módulo.
As alterações ao terceiro número indicam alterações não interruptivas, como novos parâmetros, amostras atualizadas ou novos testes.
Ao listar versões, o PowerShell ordenará as versões como cadeias de carateres, pelo 1.01.0 que serão tratadas como maiores do que 1.001.0.

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

Não suporta cadeias de pré-lançamento em números de versão. Isto é útil quando um publicador pretende entregar uma versão de pré-visualização de uma nova versão principal depois de fornecer uma versão 1.0.0. Isto será suportado numa versão futura dos cmdlets Galeria do PowerShell e PowerShellGet.
O PowerShell e o Galeria do PowerShell permitem cadeias de versão com 1, 2 e 4 segmentos. Muitos módulos iniciais não seguiram 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 controlo de versões, estas diferenças são ignoradas.

Testar com um repositório local

O Galeria do PowerShell não foi concebido para ser um destino para testar o processo de publicação. A melhor forma de testar o processo ponto a ponto da publicação no Galeria do PowerShell é configurar e utilizar o seu próprio repositório local. Isto pode ser feito de algumas formas, incluindo:

Configure uma instância de Galeria do PowerShell local com o projeto galeria privada PS no GitHub. Este projeto de pré-visualização irá ajudá-lo a configurar uma instância do Galeria do PowerShell que pode controlar e a utilizar para os seus testes.
Configure um repositório Nuget interno. Isto requer mais trabalho para configurar, mas terá a vantagem de validar mais alguns dos requisitos, nomeadamente validar a utilização de uma chave de API e se as dependências estão ou não presentes no destino quando publicar.
Configure uma partilha de ficheiros como o repositório de teste. Isto é fácil de configurar, mas como é uma partilha de ficheiros, as validações indicadas acima não terão lugar. Uma vantagem potencial neste caso é que a partilha de ficheiros não verifica a chave de API necessária, pelo que pode utilizar a mesma chave que utilizaria para publicar no Galeria do PowerShell.

Com qualquer uma destas soluções, utilize Register-PSRepository para definir um novo repositório, que utiliza no -Repository parâmetro para Publish-Module.

Um ponto adicional sobre a publicação de testes: qualquer pacote que publique no Galeria do PowerShell não pode ser eliminado sem a ajuda da equipa de operações, que confirmará que nada depende do pacote que pretende publicar. Por esse motivo, não suportamos o Galeria do PowerShell como um destino de teste e entraremos em contacto com qualquer editor que o faça.

Utilizar o PowerShellGet para publicar

Recomenda-se vivamente que os editores utilizem os Publish-Module cmdlets e Publish-Script ao trabalhar com o Galeria do PowerShell. O PowerShellGet foi criado para o ajudar a evitar memorizar detalhes importantes sobre como instalar e publicar no Galeria do PowerShell. Ocasionalmente, os editores optaram por ignorar o PowerShellGet e utilizar o cliente NuGet ou cmdlets PackageManagement , em vez de Publish-Module. Existem vários detalhes que são facilmente ignorados, o que resulta numa variedade de pedidos de suporte.

Se existir uma razão para não poder utilizar Publish-Module ou Publish-Script, informe-nos. Crie um problema no repositório Do PowerShellGet GitHub e forneça os detalhes que fazem com que escolha NuGet ou PackageManagement.

Fluxo de trabalho recomendado

A abordagem mais bem-sucedida que encontrámos para os pacotes publicados no Galeria do PowerShell é a seguinte:

Efetue o desenvolvimento inicial num site de projeto open source. A Equipa do PowerShell utiliza o GitHub.
Utilize os comentários dos revisores e do Analisador de Scripts do PowerShell para obter o código para o estado estável.
Inclua documentação, para que outras pessoas saibam como utilizar o seu trabalho.
Teste a ação de publicação com um repositório local.
Publique uma versão estável ou Alfa no Galeria do PowerShell, certificando-se de que inclui a documentação e a ligação para o site do projeto.
Recolha feedback e itere no código no seu site de projeto e, em seguida, publique atualizações estáveis no Galeria do PowerShell.
Adicione exemplos e testes do Pester no projeto e no módulo.
Decida se pretende criar um código para assinar o seu pacote.
Quando sentir que o projeto está pronto para ser utilizado num ambiente de produção, publique uma 1.0.0 versão no Galeria do PowerShell.
Continue a recolher feedback e iterar o seu código com base na entrada do utilizador.

Share via