Perguntas frequentes sobre a Galeria do PowerShell

Um módulo do PowerShell é um pacote reutilizável que contém algumas funcionalidades do PowerShell. Tudo no PowerShell (funções, variáveis, recursos de DSC etc.) pode ser empacotado em módulos. Normalmente, os módulos são pastas que contêm tipos específicos de arquivos armazenados em um caminho específico. Há alguns tipos diferentes de módulos do PowerShell por aí.

Um script do PowerShell é uma série de comandos que são armazenados em um arquivo .ps1 para habilitar o compartilhamento e a reutilização. Fluxos de trabalho do PowerShell também são scripts do PowerShell, que descrevem um conjunto de tarefas e fornecem o sequenciamento dessas tarefas. Para obter mais informações, visite Introdução ao fluxo de trabalho do PowerShell.

Normalmente, os módulos são melhores para compartilhamento, mas nós estamos habilitando o compartilhamento de scripts para facilitar que você contribua com fluxos de trabalho e scripts para a comunidade. Para obter mais informações, consulte os blogs a seguir:

• Don't Write Scripts, Write PowerShell Modules (Não escreva scripts, escreva módulos do PowerShell)
• Understanding PowerShell Modules (Entendendo os módulos do PowerShell)

Você precisa registrar uma conta na Galeria do PowerShell antes que possa publicar pacotes na Galeria. Isso ocorre porque a publicação de pacotes requer uma NuGetApiKey, que é fornecida no registro. Para se registrar, use sua conta pessoal, corporativa ou de estudante para entrar na Galeria do PowerShell. Um processo de registro único é necessário quando você entra pela primeira vez. Posteriormente, a NuGetApiKey fica disponível em sua página de perfil.

Após ter se registrado na Galeria, use os cmdlets Publish-Module ou Publish-Script para publicar seu pacote na Galeria. Para obter mais detalhes sobre como executar esses cmdlets, visite a guia Publicar ou leia a documentação sobre Publish-Module e Publish-Script.

Você não precisa se registrar ou entrar na Galeria para instalar ou salvar pacotes.

A mensagem de erro completa é: "Falha ao processar a solicitação". "A chave de API especificada é inválida ou não tem permissão para acessar o pacote especificado." O servidor remoto retornou um erro: (403) Proibido."

Esse erro pode ocorrer por um dos seguintes motivos:

• A chave de API especificada é inválida. Confirme se você especificou a chave de API válida de sua conta. Para obter sua chave de API, exiba sua página de perfil.
• O nome do pacote especificado não pertence a você. Se você tiver confirmado que a chave de API está correta, talvez já exista um pacote com o mesmo nome do que você está tentando usar. O pacote pode ter sido removido da lista pelo proprietário. Nesse caso, ele não será exibido nos resultados da pesquisa. Para determinar se um pacote com o mesmo nome já existe, abra um navegador e navegue até a página de detalhes do pacote: https://www.powershellgallery.com/packages/<packageName>. Por exemplo, navegar diretamente até https://www.powershellgallery.com/packages/pester levará você à página de detalhes do módulo Pester, quer ele seja removido da lista ou não. Se um pacote com um nome conflitante já existir e não estiver listado, você poderá:
  • Selecionar outro nome para o pacote.
  • Entrar em contato com os proprietários do pacote existente.

Esteja ciente de que sua conta da Galeria não acomoda alterações no seu alias do email principal. Para obter mais informações, consulte Aliases de Email da Microsoft.

Ao marcar uma caixa de seleção Categoria, você está afirmando "Gostaria de ver todos os pacotes nesta categoria". Somente os pacotes nas categorias selecionadas serão exibidos. Da mesma forma, marcando todas as caixas de seleção Categoria, você está afirmando "Gostaria de ver todos os pacotes em qualquer categoria". Mas alguns pacotes na galeria não pertencem a nenhuma das categorias listadas, portanto, eles não aparecerão nos resultados. Para ver todos os pacotes da Galeria, desmarque todas as Categorias ou selecione a guia Pacotes novamente.

Qualquer tipo de módulo do PowerShell (módulos de script, módulos binários ou módulos de manifesto) pode ser publicado na Galeria. Para publicar um módulo, o PowerShellGet precisa saber algumas coisas sobre ele – a versão, a descrição, o autor e como ele está licenciado. Essas informações são lidas como parte do processo de publicação do manifesto do módulo arquivo (.psd1) ou do valor do parâmetro LicenseUri do cmdlet Publish-Module. Todos os módulos publicados na Galeria devem ter manifestos de módulo. Qualquer módulo que incluir as seguintes informações em seu manifesto pode ser publicado na Galeria:

• Versão
• Descrição
• Autor
• Um URI para os termos de licença do módulo, como parte da seção PrivateData do manifesto ou no parâmetro LicenseUri do cmdlet Publish-Module.

A maneira mais fácil de criar um manifesto de módulo é executar o cmdlet New-ModuleManifest. No PowerShell 5.0 ou mais recente, New-ModuleManifest gera um manifesto de módulo formatado corretamente com campos em branco para metadados úteis, como ProjectUri, LicenseUri e Tags. Basta preencher os espaços em branco ou usar o manifesto gerado como um exemplo da formatação correta.

Para verificar se todos os campos de metadados obrigatórios foram preenchidos corretamente, use o cmdlet Test-ModuleManifest.

Para atualizar os campos do arquivo de manifesto do módulo, use o cmdlet Update-ModuleManifest.

Qualquer tipo de script do PowerShell (scripts ou fluxos de trabalho) pode ser publicado na Galeria. Para publicar um script, o PowerShellGet precisa saber algumas coisas sobre ele – a versão, a descrição, o autor e como ele está licenciado. Essas informações são lidas como parte do processo de publicação da seção PSScriptInfo do arquivo de script ou do valor do parâmetro LicenseUri do cmdlet Publish-Script. Todos os scripts publicados na Galeria devem ter informações dos metadados. Qualquer script que incluir as seguintes informações em sua seção PSScriptInfo pode ser publicado na Galeria:

• Versão
• Descrição
• Autor
• Um URI para os termos de licença do script, como parte da seção PSScriptInfo do manifesto ou no parâmetro LicenseUri do cmdlet Publish-Script.

Digite o que você está procurando na caixa de texto. Por exemplo, se quiser localizar os módulos relacionados ao SQL do Azure, basta digitar "azure sql". Nosso mecanismo de pesquisa procurará por essas palavras-chave em todos os pacotes publicados, inclusive nos títulos, descrições e metadados. Em seguida, com base em uma pontuação de qualidade ponderada, ele exibirá as correspondências mais próximas. Você também pode pesquisar por um campo específico usando a sintaxe campo: "valor" na consulta de pesquisa para os seguintes campos:

• Marcas
• Funções
• Cmdlets
• DscResources
• PowerShellVersion

Portanto, por exemplo, quando você pesquisa PowerShellVersion: "2.0", apenas os resultados compatíveis com o PowerShellVersion 2.0 (com base em seu manifesto de módulo/script) serão exibidos.

A maneira mais fácil de criar um arquivo de script formatado corretamente é executar o cmdlet New-ScriptFileInfo. No PowerShell 5.0, New-ScriptFileInfo gera um arquivo de script formatado corretamente com campos em branco para metadados úteis, como ProjectUri, LicenseUri e Tags. Basta preencher os espaços em branco ou usar o arquivo de script gerado como um exemplo da formatação correta.

Para verificar se todos os campos de metadados obrigatórios foram preenchidos corretamente, use o cmdlet Test-ScriptFileInfo.

Para atualizar os campos de metadados do script, use o cmdlet Update-ScriptFileInfo.

O termo módulo do PowerShell também se refere aos arquivos que implementam a funcionalidade real. Arquivos de módulo de script (.psm1) contêm código do PowerShell. Arquivos de módulo binários (.dll) contêm código compilado.

Esta é uma forma de pensar neles: a pasta que encapsula o módulo é a pasta de módulo. A pasta de módulo pode conter um manifesto de módulo (.psd1) que descreve o conteúdo da pasta. Os arquivos que realmente fazem o trabalho são os arquivos de módulo de script (.psm1) e os arquivos de módulo binário (.dll). Os recursos de DSC ficam localizados em uma subpasta específica e são implementados como arquivos de módulo de script ou de módulo binário.

Todos os módulos na Galeria contêm manifestos de módulo e a maioria desses módulos contêm arquivos de módulo de script ou módulo binário. O termo módulo pode ser confuso devido a esses significados diferentes. A menos que seja indicado explicitamente o contrário, todos os usos da palavra módulo nesta página fazem referência à pasta de módulo que contém esses arquivos.

PackageManagement é uma interface comum para trabalhar com qualquer gerenciador de pacotes. Quer esteja lidando com módulos do PowerShell, MSIs, RubyGems, pacotes do NuGet ou módulos do Perl, você deve ser capaz de usar comandos do PackageManagement (Find-Package e Install-Package) para localizar e instalá-los. PackageManagement faz isso tendo um provedor de pacote para cada gerenciador de pacotes que se conecta a ele. Os provedores fazem todo o trabalho real; eles buscam o conteúdo de repositórios e instalam o conteúdo localmente. Frequentemente, os provedores de pacote simplesmente encapsulam as ferramentas do gerenciador de pacotes existente para um determinado tipo de pacote.

PowerShellGet é o gerenciador de pacotes do PowerShell. Há um provedor de pacotes PSModule que expõe a funcionalidade do PowerShellGet por meio de PackageManagement. Por isso, é possível executar Install-Module ou Install-Package -Provider PSModule para instalar um módulo na Galeria do PowerShell. Algumas funcionalidades do PowerShellGet, incluindo Update-Module e Publish-Module, não podem ser acessadas por meio de comandos do PackageManagement.

Em resumo, o PowerShellGet destina-se unicamente a ter uma experiência de gerenciamento de pacotes premium para o conteúdo do PowerShell. PackageManagement destina-se a expor todas as experiências de gerenciamento de pacotes por meio de um conjunto de ferramentas geral. Se você considerar esta resposta insatisfatória, haverá uma resposta longa na parte inferior deste documento, na seção Como PackageManagement de fato está relacionado ao PowerShellGet?.

Para obter mais informações, visite a página do projeto do PackageManagement.

A Galeria do PowerShell é uma versão modificada da Galeria do NuGet. O PowerShellGet usa o provedor do NuGet para trabalhar com repositórios baseados em NuGet, como a Galeria do PowerShell.

Você pode usar o PowerShellGet com qualquer compartilhamento de arquivo ou repositório do NuGet válido. Basta adicionar o repositório executando o cmdlet Register-PSRepository.

Sim.

Nos bastidores, o PowerShellGet utiliza intensamente a infraestrutura de PackageManagement.

Na camada de cmdlet do PowerShell, Install-Module é, na verdade, um wrapper fino ao redor de Install-Package -Provider PSModule.

Na camada do provedor do pacote PackageManagement, o provedor de pacote PSModule chama outros provedores do pacote PackageManagement. Por exemplo, quando você está trabalhando com galerias baseadas em NuGet (como a Galeria do PowerShell), o provedor do pacote PSModule usa o provedor de pacote do NuGet para trabalhar com o repositório.

Figura 1: Arquitetura do PowerShellGet

De modo geral, é recomendável escolher a versão mais recente do módulo PowerShellGet (observe que ele requer o .NET 4.5).

O módulo PowerShellGet exige o PowerShell 3.0 ou mais recente.

Portanto, PowerShellGet exige um dos seguintes sistemas operacionais:

• Windows 10
• Windows 8.1 Pro
• Windows 8.1 Enterprise
• Windows 7 SP1
• Windows Server 2016
• Windows Server 2012 R2
• Windows Server 2008 R2 SP1

O PowerShellGet também requer o .NET Framework 4.5 ou posterior. Para obter mais informações, confira Instalar o .NET Framework para desenvolvedores.

Não é possível guardar nomes de pacotes. Se você acreditar que um pacote existente está usando um nome que seria mais adequado para o seu pacote, tente entrar em contato com o proprietário do pacote. Se não receber uma resposta dentro de duas semanas, entre em contato com o suporte, e a equipe da Galeria do PowerShell examinará a questão.

Confira Gerenciando proprietários do pacote em PowerShellGallery.com para obter detalhes.

Recomendamos que a comunidade do PowerShell trabalhe junta para resolver controvérsias que podem surgir entre os proprietários dos pacotes. Nós criamos um processo de solução de controvérsias e solicitamos que você o siga antes que os administradores do PowerShellGallery.com intercedam.