Empacotar valores de metadados 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 seguintes cmdlets 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 strings 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.

• 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 - Essas informações vêm da seção ReleaseNotes , em PSData\PrivateData.

• Proprietários – os 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 os proprietários de itens.

• Autor - Isso é incluído no manifesto do módulo como o Autor. O campo Autor geralmente é usado 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. Não é controlável pelas informações do manifesto. A Galeria do PowerShell cria .nuspec um arquivo que aparece na lista de arquivos de cada pacote. Esse arquivo não é instalado com o pacote em um sistema. Esse é o manifesto do pacote NuGet para o pacote e pode ser ignorado.

• Tags - As tags são incluídas PrivateData\PSData no 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 caractere 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 caractere curinga *. Ter uma lista melhora o desempenho do módulo de carga.

• Recursos de DSC – Isso é fornecido no manifesto usando DscResourcesToExport. Esse valor só tem suporte 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 o PowerShell 5.0 e inferior, isso é controlado usando marcas. Para Desktop, use a tag PSEdition_Desktop e, para core, use a tag PSEdition_Core. Para módulos projetados para o 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 um proprietário do 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 na PrivateData\PSData 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 na PrivateData\PSData seção do manifesto do módulo especificando um IconURI. O URI deve apontar para uma imagem de 85x85 com plano de fundo transparente. 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 do script

A lista a seguir mostra os elementos da interface do usuário da página de 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 - Essas informações vêm 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, há suporte para o cenário em que um script depende de um módulo que requer aceitação de 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 .RELEASENOTES palavra-chave nos metadados baseados em comentários de um arquivo de script.

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

• Direitos autorais - Essas informações vêm 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 pelas informações do manifesto. A Galeria do PowerShell cria .nuspec um arquivo que aparece na lista de arquivos de cada pacote. Esse arquivo não é instalado com o pacote em um sistema. Esse é o manifesto do pacote NuGet para o pacote e pode ser ignorado.

• Tags - *Essas informações vêm 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 o PowerShell 5.0 e inferior, isso é controlado usando marcas. Para Desktop, use a tag PSEdition_Desktop e, para core, use a tag PSEdition_Core. Para módulos projetados para o 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 um proprietário do 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 - Essas informações vêm 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 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 - Essas informações vêm da .ICONURI palavra-chave nos metadados baseados em comentários de um arquivo de script. O URI deve apontar para uma imagem de 85x85 com plano de fundo transparente. 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 autorais
• 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 você 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 strings simples que os consumidores usam para encontrar pacotes. As tags são mais valiosas quando são usadas de forma consistente em pacotes relacionados. O uso de 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 strings 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 pesquisarão, adicione-a à descrição do pacote para que ela possa ser encontrada nos resultados da pesquisa. Use maiúsculas e minúsculas, hífens, sublinhados ou pontos Pascal para melhorar a legibilidade. Tenha cuidado ao criar tags longas, complexas e incomuns que são facilmente digitadas incorretamente.

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

Conforme observado anteriormente, as marcas fornecem o maior valor quando são específicas e usadas de forma consistente em muitos pacotes. Como um editor tentando localizar as melhores marcas a serem usadas, a abordagem mais fácil é pesquisar na Galeria do PowerShell as marcas que você está considerando. Idealmente, os pacotes retornados se alinham com o uso dessa palavra-chave.

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