Valores de metadados de pacote que afetam a interface do usuário da Galeria do PowerShell

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 cmdlets a seguir são usados para criar ou atualizar esses metadados:

• New-ModuleManifest
• Update-ModuleManifest
• New-ScriptFileInfo
• Update-ScriptFileInfo

Elementos de recurso da Galeria do PowerShell controlados pelo manifesto do módulo

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 é a cadeia de caracteres de versão nos metadados e um rótulo de pré-lançamento, se especificado. 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 de módulo de pré-lançamento.

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

• Exigir 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 fornecendo um license.txt arquivo na raiz da pasta do módulo. Para obter mais informações, consulte Exigir aceitação de licença.

• Notas de versão - Estas informações são provenientes da secção Notas de Versão , em PSData\PrivateData.

• Proprietários - Proprietários são a lista de usuários na Galeria do PowerShell que podem atualizar um pacote. A lista de proprietários não está incluída no manifesto do pacote. A documentação adicional descreve como gerenciar proprietários de itens.

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

• Copyright - Este é o campo Copyright no manifesto do módulo.

• FileList - A lista de arquivos é criada quando o pacote é publicado na Galeria do PowerShell. Não é controlável pela informação do manifesto. A Galeria do PowerShell cria .nuspec um arquivo que aparece na lista de arquivos de cada pacote. Este arquivo não é instalado com o pacote em um sistema. Este é o manifesto do pacote NuGet para o pacote e pode ser ignorado.

• Etiquetas - As tags são incluídas no PrivateData\PSData manifesto do módulo. As tags têm requisitos e significados específicos que são descritos na seção Detalhes da tag .

• Cmdlets - Isso é fornecido no manifesto do módulo usando CmdletsToExport. É uma prática recomendada listar explicitamente os nomes dos cmdlets em vez de usar o curinga *. Ter uma lista melhora o desempenho do módulo de carga.

• Funções - Isso é fornecido no manifesto do módulo usando FunctionsToExport. É uma prática recomendada listar explicitamente os nomes dos cmdlets em vez de usar o curinga *. Ter uma lista melhora o desempenho do módulo de carga.

• Recursos DSC - Isso é fornecido no manifesto usando DscResourcesToExport. Esse valor só é suportado para módulos no PowerShell 5.0 e superior.

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

• Edições do PowerShell - Para módulos projetados para PowerShell 5.0 e inferiores, isso é controlado usando Tags. Para o Ambiente de Trabalho, utilize a etiqueta PSEdition_Desktop e, para o núcleo, utilize a etiqueta PSEdition_Core. Para módulos projetados para PowerShell 5.1 e superior, há uma chave CompatiblePSEditions no manifesto. Para obter mais informações, consulte Suporte PSEdition para módulos.

• Dependências - Isso é fornecido no manifesto usando RequiredModules.

• Versão mínima do PowerShell - Isso é fornecido no manifesto usando PowerShellVersion.

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

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

• Licença - Um link de licença é fornecido para módulos PrivateData\PSData na seção do manifesto do módulo, especificando um LicenseURI.

  Importante

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

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

Elementos de recurso da Galeria do PowerShell controlados pelos metadados de script

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 que é publicado na Galeria

• Versão - A versão exibida é a cadeia de caracteres de versão nos metadados e um rótulo de pré-lançamento, se especificado. O valor vem da .VERSION palavra-chave no bloco de comentários 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 - Esta informação vem da .DESCRIPTION palavra-chave na ajuda baseada em comentários de um arquivo de script.

• Exigir aceitação de licença - A aceitação de licença não é suportada para scripts. No entanto, o cenário em que um script depende de um módulo que requer aceitação de licença é suportado. Para obter mais informações, consulte Exigindo aceitação de licença para scripts.

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

• Proprietários - Proprietários são a lista de usuários na Galeria do PowerShell que podem atualizar um pacote. 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 - Esta informação vem da .AUTHOR palavra-chave nos metadados baseados em comentários de um arquivo de script. O campo Autor é frequentemente usado para especificar uma empresa ou organização associada a um pacote.

• Copyright - Esta informação vem da .COPYRIGHT palavra-chave 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. Não é controlável pela informação do manifesto. A Galeria do PowerShell cria .nuspec um arquivo que aparece na lista de arquivos de cada pacote. Este arquivo não é instalado com o pacote em um sistema. Este é o manifesto do pacote NuGet para o pacote e pode ser ignorado.

• Tags - *Esta informação vem da .TAGS palavra-chave nos metadados baseados em comentários de um arquivo de script. As tags têm requisitos e significados específicos que são descritos na seção Detalhes da tag .

• Edições do PowerShell - Para módulos projetados para PowerShell 5.0 e inferiores, isso é controlado usando Tags. Para o Ambiente de Trabalho, utilize a etiqueta PSEdition_Desktop e, para o núcleo, utilize a etiqueta PSEdition_Core. Para módulos projetados para PowerShell 5.1 e superior, há uma chave CompatiblePSEditions no manifesto. Para obter mais informações, consulte Suporte PSEdition para módulos.

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

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

• Licença - Esta informação vem da .LICENSEURI palavra-chave nos metadados baseados em comentários de um arquivo de script.

  Importante

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

• Ícone - Esta informação vem da .ICONURI palavra-chave nos metadados baseados em comentários de um arquivo de script. O URI deve apontar para uma imagem 85x85 com fundo de transparência. O URI deve ser um link direto para o arquivo de imagem e não deve ir para uma página da Web ou um arquivo no pacote da Galeria do PowerShell.

Editando detalhes do pacote

A página Editar pacote da Galeria do PowerShell permite que os editores alterem vários dos campos exibidos para um pacote, especificamente:

• Title
• Description
• Resumo
• URL do ícone
• URL da página inicial do projeto
• Autores
• Direitos de autor
• Etiquetas
• Notas de lançamento
• 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 informações na Galeria, deverá publicar uma nova versão do pacote com as mesmas alterações.

Detalhes da tag

As tags são cadeias de caracteres simples que os consumidores usam para encontrar pacotes. As tags são mais valiosas quando são usadas de forma consistente em pacotes relacionados. Usar variações da mesma palavra, por exemplo, banco de dados e bancos de dados ou teste e teste, oferece poucos benefícios. As tags são cadeias de caracteres que não diferenciam maiúsculas de minúsculas de uma única palavra e não podem incluir espaços em branco. Se houver uma frase que você acredita que os usuários irão pesquisar, adicione-a à descrição do pacote para que ela possa ser encontrada nos resultados da pesquisa. Use invólucro, hífenes, sublinhados ou pontos Pascal para melhorar a legibilidade. Seja cauteloso ao criar tags longas, complexas e incomuns que são facilmente escritas incorretamente.

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

Como observado anteriormente, as tags fornecem mais valor quando são específicas e usadas de forma consistente em muitos pacotes. Como um editor tentando localizar as melhores tags para usar, a abordagem mais fácil é pesquisar na Galeria do PowerShell por tags que você está considerando. O ideal é que os pacotes retornados estejam alinhados com o uso dessa palavra-chave.

A tabela a seguir mostra algumas das tags mais usadas. A tag preferida deve retornar os melhores resultados de pesquisa.