Criar e publicar um item

A Galeria do PowerShell é o local onde pode publicar e partilhar módulos, scripts e recursos do PowerShell estáveis e Desired State Configuration (DSC) com a comunidade de utilizadores do PowerShell mais ampla.

Este artigo aborda a mecânica e os passos importantes para preparar um script ou módulo e publicá-lo no Galeria do PowerShell. Recomendamos vivamente que reveja as Diretrizes de Publicação para compreender como garantir que os itens que publicar serão mais amplamente aceites pelos utilizadores Galeria do PowerShell.

Os requisitos mínimos para publicar um item no Galeria do PowerShell são:

• Ter uma conta Galeria do PowerShell e a Chave de API associada
• Certifique-se de que os Metadados Necessários estão no item
• Utilize as ferramentas de pré-validação para garantir que o item está pronto para ser publicado
• Publicar o item no Galeria do PowerShell com os comandos Publish-Module e Publish-Script
• Responder a perguntas ou preocupações sobre o seu item

O Galeria do PowerShell aceita módulos do PowerShell e scripts do PowerShell. Quando nos referimos a scripts, referimo-nos a um script do PowerShell que é um único ficheiro e não faz parte de um módulo maior.

Galeria do PowerShell Conta e Chave de API

Veja Criar uma Conta de Galeria do PowerShell para saber como configurar a sua conta de Galeria do PowerShell.

Depois de criar uma conta, pode obter a Chave de API necessária para publicar um item. Depois de iniciar sessão com a conta, o seu nome de utilizador será apresentado na parte superior da Galeria do PowerShell páginas em vez de Registar. Clicar no seu nome de utilizador irá levá-lo para a página A Minha Conta, onde encontrará a Chave de API.

Metadados Necessários para Itens Publicados no Galeria do PowerShell

O Galeria do PowerShell fornece informações aos utilizadores da galeria retirados dos campos de metadados incluídos no script ou manifesto do módulo. Criar ou modificar itens para publicação no Galeria do PowerShell tem um pequeno conjunto de requisitos para informações fornecidas no manifesto do item. Recomendamos vivamente que reveja a secção Metadados de Itens das Diretrizes de Publicação para saber como fornecer as melhores informações aos utilizadores com os seus itens.

Os cmdlets New-ModuleManifest e New-ScriptFileInfo irão criar o modelo de manifesto por si, com marcadores de posição para todos os elementos de manifesto.

Ambos os manifestos têm duas secções importantes para a publicação, a área Dados de Chave Primária e PSData de PrivateData. Os dados de chave primária num manifesto do módulo do PowerShell estão todos fora da secção PrivateData. O conjunto de chaves primárias está associado à versão do PowerShell em utilização e não são suportadas. O PrivateData suporta a adição de novas chaves, pelo que os elementos específicos do Galeria do PowerShell estão no PSData.

Os elementos de manifesto que são mais importantes para preencher para o item que publicar no Galeria do PowerShell são:

• Script ou Nome do Módulo – estes são obtidos a partir dos nomes do .PS1 de um script ou do . PSD1 para um módulo.
• Versão – esta é uma chave primária necessária, o formato deve seguir as diretrizes do SemVer. Veja Melhores Práticas para obter detalhes.
• Autor – esta é uma chave primária necessária e contém o nome a ser associado ao item. Veja Autores e Proprietários abaixo.
• Descrição – esta é uma chave primária necessária, utilizada para explicar resumidamente o que este item faz e quaisquer requisitos para utilizá-lo
• ProjectURI – este é um campo de URI altamente recomendado no PSData que fornece uma ligação para um repositório do GitHub ou uma localização semelhante onde efetua o desenvolvimento no item
• Etiquetas – é uma recomendação forte etiquetar o seu pacote com base na respetiva compatibilidade com PSEditions e plataformas. Para obter detalhes, veja As Diretrizes de Publicação.

Os autores e proprietários de Galeria do PowerShell itens são conceitos relacionados, mas nem sempre correspondem. Os Proprietários de Itens são utilizadores com contas Galeria do PowerShell que têm permissão para manter o item. Podem existir muitos Proprietários que podem atualizar qualquer item. O Proprietário só está disponível a partir do Galeria do PowerShell e perde-se se o item for copiado de um sistema para outro. O autor é uma cadeia incorporada nos dados de manifesto, pelo que faz sempre parte do item. As recomendações para itens de produtos Microsoft são:

• Ter vários proprietários, sendo que pelo menos um é o nome da equipa que produz o item
• Fazer com que o Autor seja um nome de equipa conhecido (como Equipa do SDK do Azure) ou Microsoft Corporation

Pré-validar o item

Existem algumas ferramentas que precisa de executar no código antes de publicar o item no Galeria do PowerShell:

• Analisador de Scripts do PowerShell, que está no Galeria do PowerShell
• Para módulos, Test-ModuleManifest que faz parte do PowerShell
• Para scripts, Test-ScriptFileInfo fornecidos com o PowerShell Get

O Analisador de Scripts do PowerShell é uma ferramenta de análise de código estático que irá analisar o seu código para garantir que cumpre as diretrizes básicas de codificação do PowerShell. Esta ferramenta irá identificar problemas comuns e críticos no seu código e deve ser executada regularmente durante o desenvolvimento para ajudá-lo a preparar o item para publicar. O Analisador de Scripts do PowerShell fornecerá uma lista de problemas identificados como Erros, Aviso e Informações. Todos os erros têm de ser resolvidos antes de publicar no Galeria do PowerShell. Os avisos têm de ser revistos e a maioria deve ser abordada. O Analisador de Scripts do PowerShell é executado sempre que um item é publicado ou atualizado no Galeria do PowerShell. A equipa de Operações da Galeria contactará os proprietários dos itens para resolver os erros encontrados.

Se as informações do manifesto no item não puderem ser lidas pela infraestrutura de Galeria do PowerShell, não poderá publicar. Test-ModuleManifest irá detetar problemas comuns que fariam com que o módulo não fosse utilizável quando está instalado. Tem de ser executado para cada módulo antes de o publicar no Galeria do PowerShell.

Da mesma forma, Test-ScriptFileInfo valida os metadados num script e tem de ser executado em todos os scripts (publicados separados de um módulo) antes de os publicar no Galeria do PowerShell.

Itens de Publicação

Tem de utilizar Publish-Script ou Publish-Module para publicar itens no Galeria do PowerShell. Ambos os comandos requerem:

• O caminho para o item que irá publicar. Para um módulo, utilize a pasta com o nome para o seu módulo. Se especificar uma pasta que contenha várias versões do mesmo módulo, tem de especificar RequiredVersion.
• Uma chave de API Nuget. Esta é a chave de API encontrada na página A Minha Conta no Galeria do PowerShell.

A maioria das outras opções na linha de comandos deve estar nos dados de manifesto do item que está a publicar, pelo que não deve ter de as especificar no comando .

Para evitar erros, recomendamos vivamente que experimente os comandos com -WhatIf -Verbose antes de publicar. Isto poupará tempo considerável, uma vez que sempre que publicar no Galeria do PowerShell, tem de atualizar o número da versão na secção de manifesto do item.

Os exemplos seriam:

• Publish-Module -Path ".\MyModule" -NugetAPIKey "GUID" -WhatIf -Verbose
• Publish-Script -Path ".\MyScriptFile.PS1" -NugetAPIKey "GUID" -WhatIf -Verbose

Reveja cuidadosamente o resultado e, se não vir erros ou avisos, repita o comando sem -WhatIf.

Todos os itens publicados no Galeria do PowerShell serão analisados quanto a vírus e serão analisados com o Analisador de Scripts do PowerShell. Quaisquer problemas que surjam nessa altura serão enviados de volta para o publicador para resolução.

Depois de publicar um item no Galeria do PowerShell, terá de watch para obter feedback sobre o seu item.

• Certifique-se de que monitoriza o endereço de e-mail associado à conta utilizada para publicar. Os utilizadores e a equipa de Operações do Galeria do PowerShell fornecerão feedback através dessa conta, incluindo problemas da PSSA ou análises antivírus. Se a conta de e-mail for inválida ou se forem comunicados problemas graves à conta e não forem resolvidos durante muito tempo, os itens podem ser considerados abandonados e serão removidos do Galeria do PowerShell conforme descrito nos nossos Termos de Utilização.