Compartilhar via

Metadados de pacotes que afetam a interface do usuário da Galeria do PowerShell

  • Artigo

Este artigo explica como os metadados em seus pacotes são usados pela Galeria do PowerShell. Para módulos, os metadados são armazenados no manifesto do módulo. Para scripts, os metadados são armazenados usando palavras-chave baseadas em comentários. Os seguintes cmdlets são usados para criar ou atualizar esses metadados:

A lista a seguir mostra os elementos da interface do usuário da página do pacote da Galeria do PowerShell que são controlados pelo manifesto do módulo.

  • Título – O nome do pacote publicado na Galeria.

  • Versão – A versão exibida representa a cadeia de caracteres da versão nos metadados e uma etiqueta de pré-lançamento, se especificada. A cadeia de caracteres de pré-lançamento especificada é acrescentada ao ModuleVersion. Para obter informações sobre cadeias de caracteres de pré-lançamento em módulos, consulte Versões do módulo de pré-lançamento.

  • Descrição – Esta é a Descrição no manifesto do módulo.

  • Exige aceitação de licença – Um módulo pode exigir que o usuário aceite uma licença definindo RequireLicenseAcceptance = $true, fornecendo um LicenseURI e um arquivo license.txt na raiz da pasta do módulo. Para obter mais informações, veja Exige aceitação de licença.

  • Notas de versão – Essas informações são provenientes da seção ReleaseNotes, em PSData\PrivateData.

  • Proprietários – Os proprietários representam a lista de usuários que podem atualizar pacotes na Galeria do PowerShell. A lista de proprietários não está incluída no manifesto do pacote. A documentação adicional descreve como gerenciar proprietários do item.

  • Autor – Está incluído no manifesto de módulo como Autor. O campo Autor é usado geralmente para especificar uma empresa ou organização associada a um pacote.

  • Direitos autorais – Este é o campo Direitos autorais no manifesto do módulo.

  • FileList – A lista de arquivos é criada quando o pacote é publicado na Galeria do PowerShell. Ela não é controlada pelas informações do manifesto. A Galeria do PowerShell cria um arquivo .nuspec que aparece na lista de arquivos de cada pacote. Esse arquivo não está instalado com o pacote em um sistema. Ele é o manifesto do pacote NuGet e pode ser ignorado.

  • Marcas - Marcas estão incluídas em PrivateData\PSData, no manifesto do módulo. Elas têm requisitos e significados específicos que estão descritos na seção Detalhes de marcas.

  • Cmdlets – São fornecidos no manifesto de módulo usando CmdletsToExport. É uma melhor prática listar explicitamente os nomes de cmdlet em vez de usar o curinga *. Ter uma lista melhora o desempenho do módulo de carga.

  • Funções – São fornecidas no manifesto de módulo usando FunctionsToExport. É uma melhor prática listar explicitamente os nomes de cmdlet em vez de usar o curinga *. Ter uma lista melhora o desempenho do módulo de carga.

  • Recursos DSC – São fornecidos no manifesto usando DscResourcesToExport. Esse valor só tem suporte para módulos no PowerShell 5.0 e versões superiores.

  • Funcionalidades de função – As funções são listadas quando o módulo tem um ou mais arquivos de funcionalidade de função (.psrc). Esses arquivos são usados pelo JEA. Para obter mais informações, consulte funcionalidades de função.

  • Edições do PowerShell – Para módulos projetados para o PowerShell 5.0 e inferiores, isso é controlado usando Marcas. Para o Desktop, use a marca PSEdition_Desktop. No caso do núcleo, use a marca PSEdition_Core. Para módulos projetados para o PowerShell 5.1 e versões superiores, há uma chave CompatiblePSEditions no manifesto. Para obter mais informações, consulte Suporte do PSEdition para módulos.

  • Dependências – São fornecidas no manifesto usando RequiredModules.

  • Versão mínima do PowerShell – É fornecida no manifesto usando PowerShellVersion.

  • Histórico de versão – Mostra uma lista de versões do módulo que foram publicadas na Galeria. Pacotes ocultos usando o recurso Excluir não são exibidos no histórico de versão, a menos que você seja um proprietário do pacote.

  • Site do projeto – O site do projeto é fornecido para os módulos na seção PrivateData\PSData do manifesto de módulo especificando um ProjectURI.

  • Licença – O link da licença é fornecido para os módulos na seção PrivateData\PSData do manifesto de módulo especificando uma propriedade LicenseURI.

    Importante

    Se uma licença não for fornecida por meio do LicenseURI ou dentro do pacote, os Termos de Uso para a Galeria do PowerShell se aplicarão ao pacote. Para obter mais informações, consulte os Termos de Uso.

  • Ícone – Um link é fornecido para os módulos na seção PrivateData\PSData do manifesto de módulo especificando um IconURI. O URI deve apontar para uma imagem 85x85 com segundo plano transparente. O URI deve ser um link direto para o arquivo de imagem e não deve conduzir para uma página da Web ou um arquivo no pacote da Galeria do PowerShell.

A lista a seguir mostra os elementos da interface do usuário da página do pacote da Galeria do PowerShell que são controlados pelos metadados baseados em comentários em um arquivo de script.

  • Título – Este é o nome do pacote publicado na Galeria

  • Versão – A versão exibida representa a cadeia de caracteres da versão nos metadados e uma etiqueta de pré-lançamento, se especificada. O valor vem da palavra-chave .VERSION no bloco de comentário de metadados. Ao publicar o script de pré-lançamento, acrescente a cadeia de caracteres de pré-lançamento à versão. Para obter informações sobre como especificar cadeias de caracteres de pré-lançamento em módulos, consulte Versões de pré-lançamento de scripts.

  • Descrição – Essas informações vêm da palavra-chave .DESCRIPTION na ajuda baseada em comentários de um arquivo de script.

  • Exigir aceitação da licença – a aceitação da licença não tem suporte para scripts. No entanto, há suporte para o cenário em que um script depende de um módulo que exige a aceitação da licença. Para obter mais informações, consulte Exigir aceitação de licença para scripts.

  • Notas de versão – Essas informações vêm da palavra-chave .RELEASENOTES nos metadados baseados em comentários de um arquivo de script.

  • Proprietários – Os proprietários representam a lista de usuários que podem atualizar pacotes na Galeria do PowerShell. A lista de proprietários não está incluída no manifesto do pacote. Para obter mais informações, consulte Gerenciar proprietários de itens.

  • Autor – Essas informações vêm da palavra-chave .AUTHOR nos metadados baseados em comentários de um arquivo de script. O campo Autor é usado geralmente para especificar uma empresa ou organização associada a um pacote.

  • Direitos autorais – Essas informações vêm da palavra-chave .COPYRIGHT nos metadados baseados em comentários de um arquivo de script.

  • FileList – A lista de arquivos é criada quando o pacote é publicado na Galeria do PowerShell. Ela não é controlada pelas informações do manifesto. A Galeria do PowerShell cria um arquivo .nuspec que aparece na lista de arquivos de cada pacote. Esse arquivo não está instalado com o pacote em um sistema. Ele é o manifesto do pacote NuGet e pode ser ignorado.

  • Marcas – Essas informações vêm da palavra-chave .TAGS nos metadados baseados em comentários de um arquivo de script. Elas têm requisitos e significados específicos que estão descritos na seção Detalhes de marcas.

  • Edições do PowerShell – Para módulos projetados para o PowerShell 5.0 e inferiores, isso é controlado usando Marcas. Para o Desktop, use a marca PSEdition_Desktop. No caso do núcleo, use a marca PSEdition_Core. Para módulos projetados para o PowerShell 5.1 e versões superiores, há uma chave CompatiblePSEditions no manifesto. Para obter mais informações, consulte Suporte do PSEdition para módulos.

  • Histórico de versão – Mostra uma lista de versões do módulo que foram publicadas na Galeria. Pacotes ocultos usando o recurso Excluir não são exibidos no histórico de versão, a menos que você seja um proprietário do pacote.

  • Site do projeto – Essas informações vêm da palavra-chave .PROJECTURI nos metadados baseados em comentários de um arquivo de script.

  • Licença – Essas informações vêm da palavra-chave .LICENSEURI nos metadados baseados em comentários de um arquivo de script.

    Importante

    Se uma licença não for fornecida por meio do .LICENSEURI ou dentro do pacote, os Termos de Uso para a Galeria do PowerShell se aplicarão ao pacote. Para obter mais informações, consulte os Termos de Uso.

  • Ícone – Essas informações vêm da palavra-chave .ICONURI nos metadados baseados em comentários de um arquivo de script. O URI deve apontar para uma imagem 85x85 com segundo plano transparente. O URI deve ser um link direto para o arquivo de imagem e não deve conduzir para uma página da Web ou um arquivo no pacote da Galeria do PowerShell.

Editar detalhes do pacote

A página Editar pacote, na Galeria do PowerShell, permite aos editores alterar vários campos exibidos de um pacote, especificamente:

  • Title
  • DESCRIÇÃO
  • Resumo
  • URL do ícone
  • URL da página inicial do projeto
  • Autores
  • Direitos autorais
  • Marcas
  • Notas de versão
  • Exigir licença

Você só deve editar essas informações na Galeria para corrigir o que é exibido para uma versão mais antiga de um módulo. Os usuários que baixarem o pacote verão que os metadados não correspondem à Galeria do PowerShell. Sempre que alterar as informações na Galeria, você deverá publicar uma nova versão do pacote com as mesmas alterações.

Detalhes de marcas

As marcas são cadeias de caracteres simples que os consumidores usam para localizar pacotes. As marcas são mais valiosas quando são usadas consistentemente entre pacotes relacionados. O uso de variações de um mesmo termo, por exemplo, banco de dados e bancos de dados ou teste e testes, normalmente traz poucos benefícios. As marcas são cadeias de caracteres de palavras únicas que não diferenciam maiúsculas e minúsculas e não podem incluir espaços. Se você acredita que os usuários vão pesquisar uma determinada frase, adicione-a à descrição do pacote para que ela seja encontrada nos resultados da pesquisa. Use maiúsculas, hifens, sublinhados ou pontos finais para melhorar a legibilidade. Cuidado ao criar marcas diferentes, longas e complexas, pois elas podem ser facilmente escritas de maneira incorreta.

Os cmdlets Galeria do PowerShell e PowerShellGet têm significados especiais para as marcas PSEdition_Desktop e PSEdition_Core. Consulte a discussão anterior das Edições do PowerShell.

Conforme observado acima, as marcas são mais eficientes quando são específicas e usadas regularmente em vários pacotes. Quando o editor tenta localizar as marcas ideais que pretende usar, a abordagem mais fácil consiste em pesquisá-las na Galeria do PowerShell. Idealmente, os pacotes retornados se alinham com o uso dessa palavra-chave.

A tabela a seguir mostra algumas das marcas usadas com mais frequência. A marca preferencial deve retornar os melhores resultados da pesquisa.

Marca preferencial Alternativas e observações
Active Directory "AD" não é usado sozinho no momento
Appveyor
Automação
AWS
Azure
AzureAD
AzureAutomation
AzureRm Usado principalmente nos módulos do AzureRM
Backup
Build
ChatOps
Nuvem
Color
Configuração
CrescendoBuilt Essa marca é adicionada automaticamente pelo Crescendo quando você exporta o módulo
Banco de dados "Databases" (plural) é menos recomendado
DBA
Implantação "Deploy" é usado com menos frequência
DevOps
DNS
Docker
DSC DesiredStateConfiguration é menos recomendado, pois é muito longo
DSCResource
DSCResourceKit
Excel
Exchange
Firewall
GIT
GitHub
Gitlab
Google
HTML
Hyper-v "HyperV" é menos comum como marca
IaaS
IIS
Json
Linux
Log Recomendamos usar "Log" como um objeto
Registro em log Recomendamos usar "Logging" como uma ação
MacOS
Monitoramento
MSI
Rede "Networking" é semelhante, porém usado com menos frequência
Office365 Recomendamos usar "Office" sem abreviação. Embora seja mais curto, "O365" é usado com menos frequência
PackageManagement
Pester
PoshBot
Relatório "Report" é um objeto
Relatório "Reporting" é uma ação e "Report" é um objeto
ResourceManager "ARM" é usado para descrever um grupo de processadores e não deve ser usado para o Azure Resource Manager
REST
Segurança "Defense" é menos preciso
SharePoint
SQL
SQLServer
Armazenamento
Teste "Testing" é menos recomendado
VersionControl "Version" é menos preciso, embora seja usado com mais frequência
VSTS
Windows
WinRM
WMI
Zip