Criar e publicar um itemCreating and Publishing an Item

A Galeria do PowerShell é o local para publicar e compartilhar recursos de DSC, scripts e módulos do PowerShell estáveis com a comunidade mais ampla de usuários do PowerShell.The PowerShell Gallery is the place to publish and share stable PowerShell modules, scripts, and DSC resources with the broader PowerShell user community.

Este artigo aborda a mecânica e etapas importantes para preparar um script ou um módulo e publicá-lo na Galeria do PowerShell.This article covers the mechanics and important steps for preparing a script or module, and publishing it to the PowerShell Gallery. Recomendamos que você examine as Diretrizes de publicação para entender como garantir que os itens publicados sejam mais aceitos pelos usuários da Galeria do PowerShell.We strongly encourage that you review the Publishing Guidelines to understand how to ensure that the items you publish will be more widely accepted by PowerShell Gallery users.

Os requisitos mínimos para publicar um item na Galeria do PowerShell são:The minimum requirements to publish an item to the PowerShell Gallery are:

  • Ter uma conta da Galeria do PowerShell e a chave de API associadaHave a PowerShell Gallery account, and the API Key associated with it
  • Garantir que os metadados necessários estejam no itemEnsure Required Metadata is in your item
  • Usar as ferramentas de pré-validação para garantir que o item esteja pronto para ser publicadoUse the pre-validation tools to ensure your item is ready to publish
  • Publicar o item na Galeria do PowerShell usando os comandos Publish-Module e Publish-ScriptPublish the item to the PowerShell Gallery using the Publish-Module and Publish-Script commands
  • Responder a perguntas ou dúvidas sobre o itemResponding to questions or concerns about your item

A Galeria do PowerShell aceita módulos do PowerShell e scripts do PowerShell.The PowerShell Gallery accepts PowerShell modules and PowerShell scripts. Quando nos referimos a scripts, queremos dizer um script do PowerShell que é um único arquivo e não faz parte de um módulo maior.When we refer to scripts, we mean a PowerShell script that is a single file, and not part of a larger module.

Consulte Creating a PowerShell Gallery Account (Criando uma conta da Galeria do PowerShell) para saber como configurar a sua conta da Galeria do PowerShell.See Creating a PowerShell Gallery Account for how to set up your PowerShell Gallery account.

Depois de criar uma conta, você poderá obter a chave de API necessária para publicar um item.Once you have created an account, you can get the API Key needed to publish an item. Depois que você entrar usando a conta, seu nome de usuário será exibido na parte superior das páginas da Galeria do PowerShell em vez de Registrar.After you sign in with the account, your username will be displayed at the top of the PowerShell Gallery pages instead of Register. Clicar em seu nome de usuário levará à página Minha conta, na qual você encontrará a chave de API.Clicking on your username will take you to the My Account page, where you will find the API Key.

Observação: a chave de API deve ser tratada com a mesma segurança que seu logon e sua senha.Note: The API Key must be treated as securely as your login and password. Com essa chave você ou qualquer outra pessoa pode atualizar qualquer item que você possua na Galeria do PowerShell.With this key you, or anyone else, can update any item you own in the PowerShell Gallery. É recomendável atualizar a chave regularmente, o que pode ser feito usando Redefinir chave na página Minha conta.We recommend updating the key regularly, which can be done using Reset Key on your My Account page.

A Galeria do PowerShell fornece informações aos usuários da galeria que são extraídas dos campos de metadados incluídos no manifesto de módulo ou de script.The PowerShell Gallery provides information to gallery users drawn from metadata fields that are included in the script or module manifest. Para criar ou modificar itens para publicação na Galeria do PowerShell, há um pequeno conjunto de requisitos quanto às informações fornecidas no manifesto do item.Creating or modifying items for publication to the PowerShell Gallery has a small set of requirements for information supplied in the item manifest. É altamente recomendado que você examine a seção de Metadados de item das Diretrizes de publicação para saber como fornecer em seus itens as melhores informações para os usuários.We strongly encourage that you review the Item Metadata section of the Publishing Guidelines to learn how to provide the best information to users with your items.

Os cmdlets New-ModuleManifest e New-ScriptFileInfo criarão o modelo de manifesto para você, com espaços reservados para todos os elementos do manifesto.The New-ModuleManifest and New-ScriptFileInfo cmdlets will create the manifest template for you, with placeholders for all the manifest elements.

Ambos os manifestos têm duas seções importantes para a publicação, a área Dados de chave primária e PSData de PrivateData Os dados de chave primária em um manifesto de módulo do PowerShell correspondem a tudo que não está na seção PrivateData.Both manifests have two sections that are important for publishing, the Primary Key Data and PSData area of PrivateData The primary key data in a PowerShell module manifest is everything outside of the PrivateData section. O conjunto de chaves primárias é vinculado à versão do PowerShell em uso e os indefinidos não têm suporte.The set of primary keys is tied to the version of PowerShell in use, and undefined are not supported. PrivateData dá suporte à adição de novas chaves, portanto, os elementos específicos da Galeria do PowerShell ficam no PSData.PrivateData supports adding new keys, so the elements specific to the PowerShell Gallery are in PSData.

Os elementos do manifesto mais importantes que devem ser preenchidos para o item publicado na Galeria do PowerShell são:Manifest elements that are most important to fill in for item you publish to the PowerShell Gallery are:

  • Nome do script ou do módulo – são extraídos dos nomes do .PS1 para um script ou do .PSD1 para um módulo.Script or Module Name - Those are drawn from the names of the .PS1 for a script, or the .PSD1 for a module.
  • Versão – é uma chave primária necessária e o formato deve seguir as diretrizes de SemVer (consulte as Práticas recomendadas para obter detalhes)Version - this is a required primary key, format should follow SemVer guidelines (see Best Practices for details)
  • Autor – é uma chave primária necessária e contém o nome a ser associado ao item (consulte Autores e Proprietários, abaixo)Author - this is a required primary key, and contains the name to be associated with the item (see Authors and Owners, below)
  • Descrição – é uma chave primária necessária, usada para explicar brevemente o que esse item faz e os requisitos para usá-loDescription - this is a required primary key, used to briefly explain what this item does and any requirements for using it
  • ProjectURI – é um campo de URI altamente recomendado em PSData que fornece um link para um repositório Github ou local semelhante ao qual você pode fazer o desenvolvimento no itemProjectURI - this is a strongly recommended URI field in PSData that provides a link to a Github repo or similar location where you do development on the item

Autores e Proprietários de itens da Galeria do PowerShell são conceitos relacionados, mas nem sempre correspondem.Authors and Owners of PowerShell Gallery items are related concepts, but do not always match.
Proprietários de item são usuários com contas da Galeria do PowerShell que têm permissão para manter o item.Item Owners are users with PowerShell Gallery accounts that have permission to maintain the item. Pode haver vários Proprietários que podem atualizar um item.There may be many Owners who can update any item. O Proprietário só está disponível na Galeria do PowerShell e será perdido se o item for copiado de um sistema para outro.The Owner is only available from the PowerShell Gallery, and is lost if the item is copied from one system to another. Autor é uma cadeia de caracteres criada nos dados do manifesto, portanto, ele sempre faz parte do item.Author is a string that is built into the manifest data, so it is always part of the item. As recomendações para itens de produtos da Microsoft são:The recommendations for items from Microsoft products are:

  • Ter várias proprietários, com pelo menos um sendo o nome da equipe que produz o item;Have multiple owners, with at least one being the name of the team that produces the item;
  • Ter o Autor como o nome de uma equipe conhecida (como a equipe do SDK do Azure) ou Microsoft Corporation.Have the Author be a well-known team name (such as Azure SDK Team), or Microsoft Corporation.

Pré-validar o ItemPre-Validate Your Item

Há algumas ferramentas que você precisa executar no código antes de publicar o item na Galeria do PowerShell:There are a few tools you need to run against your code before publishing your item to the PowerShell Gallery:

  • Analisador de Script do PowerShell, que fica na Galeria do PowerShellPowerShell Script Analyzer, which is in the PowerShell Gallery
  • Para módulos, Test-ModuleManifest que faz parte do PowerShellFor modules, Test-ModuleManifest which is part of PowerShell
  • Para scripts, Test-ScriptFileInfo que acompanha o PowerShell GetFor scripts, Test-ScriptFileInfo which comes with PowerShell Get

PowerShell Script Analyzer é uma ferramenta de análise de código estático que examina seu código para garantir que ele atenda às diretrizes de codificação básicas do PowerShell.PowerShell Script Analyzer is a static code analysis tool that will scan your code to ensure it meets basic PowerShell coding guidelines. Essa ferramenta identifica os problemas críticos e comuns no código e deve ser executada regularmente durante o desenvolvimento para ajudá-lo a preparar o item para ser publicado.This tool will identify common and critical issues in your code, and should be run regularly during development to help you get your item ready to publish. O PowerShell Script Analyzer fornecerá a lista dos problemas identificados como Erros, Aviso e Informações.PowerShell Script Analyzer will provide list of issues identified as Errors, Warning, and Information. Todos os erros deverão ser resolvidos antes que você publique na Galeria do PowerShell.All errors must be addressed before you publish to the PowerShell Gallery. Os avisos precisam ser examinados e a maioria deles deve ser resolvida.Warnings need to be reviewed, and most should be addressed. O PowerShell Script Analyzer é executado sempre que um item é publicado ou atualizado na Galeria do PowerShell.PowerShell Script Analyzer is run every time an item is published or updated in the PowerShell Gallery. A equipe de Operações de Galeria entrará em contato com os proprietários de item para resolver os erros encontrados.The Gallery Operations team will contact item owners to address errors that are found.

Se as informações de manifesto no item não puderem ser lidas pela infraestrutura da Galeria do PowerShell, você não poderá publicar.If the manifest information in your item cannot be read by the PowerShell Gallery infrastructure, you will not be able to publish. O Test-ModuleManifest detectará problemas comuns que possam fazer com que o módulo fique inutilizável ao ser instalado.Test-ModuleManifest will catch common problems that would cause the module to not be usable when it is installed. Ele deve ser executado para cada módulo antes de publicar na Galeria do PowerShell.It must be run for every module prior to publishing it to the PowerShell Gallery.

Da mesma forma, Test-ScriptFileInfo valida os metadados em um script e deve ser executado em cada script (publicado separado de um módulo) antes de publicar na Galeria do Powershell.Likewise, Test-ScriptFileInfo validates the metadata in a script, and must be run on every script (published separate from a module) prior to publishing it to the Powershell Gallery.

Publicando itensPublishing Items

Você deve usar o Publish-Script ou o Publish-Module para publicar itens na Galeria do PowerShell.You must use the Publish-Script or Publish-Module to publish items to the PowerShell Gallery. Esses dois comandos exigemThese commands both require

  • O caminho para o item que você publicará.The path to the item you will publish. Para um módulo, use a pasta denominada para o seu módulo.For a module, use the folder named for your module. Se você especificar uma pasta que contenha várias versões do mesmo módulo, você deverá especificar RequiredVersion.If you specify a folder that contains multiple versions of the same module, you must specify RequiredVersion.
  • Uma chave de API do NuGet.A Nuget API key. Esta é a chave de API encontrada na página Minha conta na Galeria do PowerShell.This is the API key found in the My Account page on the PowerShell Gallery.

A maioria das outras opções na linha de comando deve estar nos dados de manifesto do item que você está publicando, portanto, você não precisa especificá-las no comando.Most of the other options in the command line should be in the manifest data for the item you are publishing, so you should not need to specify them in the command.

Para evitar erros, é altamente recomendado que você experimente os comandos usando -Whatif -Verbose, antes da publicação.To avoid errors, it is strongly recommended that you try the commands using -Whatif -Verbose, before publishing. Isso poupará um tempo considerável, pois toda vez que você publica na Galeria do PowerShell, você deve atualizar o número de versão na seção de manifesto do item.This will seave considerable time, since every time you publish to the PowerShell Gallery, you must update the version number in the manifest section of the item.

Exemplos seriam: 'Publish-Module -Path ".\MyModule" -RequiredVersion "0.0.1" -NugetAPIKey "GUID" -Whatif -Verbose' 'Publish-Script -Path ".\MyScriptFile.PS1" -NugetAPIKey "GUID" -Whatif -Verbose'Examples would be: 'Publish-Module -Path ".\MyModule" -RequiredVersion "0.0.1" -NugetAPIKey "GUID" -Whatif -Verbose' 'Publish-Script -Path ".\MyScriptFile.PS1" -NugetAPIKey "GUID" -Whatif -Verbose'

Examine a saída com cuidado e, se não aparecerem erros ou avisos, repita o comando sem o parâmetro -Whatif.Review the output carefully, and if you see no errors or warnings, repeat the command without -Whatif.

Todos os itens que são publicados na Galeria do PowerShell serão verificados em busca de vírus e serão analisados usando o PowerShell Script Analyzer.All items that are published to the PowerShell Gallery will be scanned for viruses, and will be analyzed using the PowerShell Script Analyzer. Quaisquer problemas que surgirem no momento serão enviados ao publicador para resolução.Any issues that arise at that time will be sent back to the publisher for resolution.

Depois de publicar um item na Galeria do PowerShell, você precisará observar os comentários sobre o item.Once you have published an item to the PowerShell Gallery, you will need to watch for feedback on your item.

  • Monitore o endereço de email associado à conta usada para publicar.Ensure you monitor the email address associated with the account used to publish. Os usuários e a equipe de operações da Galeria do PowerShell fornecem comentários por meio dessa conta, incluindo problemas do PSSA ou das verificações antivírus.Users, and the PowerShell Gallery Operations team will provide feedback via that account, including issues from the PSSA or antivirus scans. Se a conta de email for inválida ou se forem relatados problemas sérios à conta que ficarem muito tempo sem resolução, os itens poderão ser considerados abandonados e serão removidos da Galeria do PowerShell, conforme descrito em nossos Termos de uso.If the email account is invalid, or if serious issues are reported to the account and left unresolved for a long time, items can be considered abandoned and will be removed from the PowerShell Gallery as described in our Terms of Use.
  • Recomendamos que você assine os Comentários de cada item da Galeria do PowerShell que você publicar.We recommend you subscribe to Comments for each PowerShell Gallery item you publish. Isso permite que você seja notificado se alguém comentar sobre seus itens na Galeria do PowerShell.This allows you to be notified if anyone comments on your items in the PowerShell Gallery. Isso é opcional, pois requer a criação de uma conta do LiveFyre.This is optional, as it requires creating an account with LiveFyre.