影响 PowerShell 库 UI 的包元数据值

  • 项目

本文介绍 PowerShell 库如何使用包中的元数据。 对于模块，元数据存储在模块清单中。 对于脚本，元数据使用基于注释的关键字进行存储。 以下 cmdlet 用于创建或更新此元数据：

以下列表显示由模块清单控制的 PowerShell 库包页 UI 的元素。

  • 标题 - 发布到库的包的名称。

  • 版本 - 显示的版本是元数据中的版本字符串以及预发行版标签（如果已指定）。 指定的预发行版字符串将追加到 ModuleVersion。 有关模块中的预发行版字符串的信息，请参阅预发行版模块版本。

  • 说明 - 这是模块清单中的“说明”。

  • 要求接受许可证 - 模块可以通过以下方式要求用户接受许可证：设置 RequireLicenseAcceptance = $true、提供 LicenseURI，并提供模块文件夹根目录中的 license.txt 文件。 有关详细信息，请参阅要求接受许可证。

  • 发行说明 - 此信息来自 PSData\PrivateData 下的 ReleaseNotes 部分。

  • 所有者 - 所有者是 PowerShell 库中可以更新包的用户列表。 所有者列表不包含在包清单中。 其他文档描述如何管理项所有者。

  • 作者 - 这作为“作者”包含在模块清单中。 “作者”字段通常用于指定与包关联的公司或组织。

  • 版权 - 这是模块清单中的“版权”字段。

  • 文件列表 - 将包发布到 PowerShell 库时会创建文件列表。 不可通过清单信息对其进行控制。 PowerShell 库创建显示在每个包的文件列表中的 .nuspec 文件。 此文件未随包一起安装在系统上。 这是对应包的 NuGet 包清单，可能会被忽略。

  • 标记 - 标记包含在模块清单中的 PrivateData\PSData 下。 标记具有特定要求和含义，这些内容将在标记详细信息部分中描述。

  • cmdlet - 这可使用 CmdletsToExport 在模块清单中提供。 最佳做法是显式列出 cmdlet 名称，而不是使用通配符 *。 有一个列表可提高加载模块性能。

  • 函数 - 这可使用 FunctionsToExport 在模块清单中提供。 最佳做法是显式列出 cmdlet 名称，而不是使用通配符 *。 有一个列表可提高加载模块性能。

  • DSC 资源 - 这可使用 DscResourcesToExport 在清单中提供。 仅 PowerShell 5.0 及更高版本中的模块支持此值。

  • 角色功能 - 当模块具有一个或多个角色功能 (.psrc) 文件时，将列出角色。 JEA 使用这些文件。 有关详细信息，请参阅角色功能。

  • PowerShell 版本 - 对于专为 PowerShell 5.0 及更低版本设计的模块，使用“标记”对此进行控制。 对于桌面，使用标记 PSEdition_Desktop；对于核心，使用标记 PSEdition_Core。 对于专为 PowerShell 5.1 及更高版本设计的模块，清单中存在 CompatiblePSEditions 键。 有关详细信息，请参阅对模块的 PSEdition 支持。

  • 依赖项 - 这可使用 RequiredModules 在清单中提供。

  • 最低 PowerShell 版本 - 这可使用 PowerShellVersion 在清单中提供。

  • 版本历史记录 - 显示已发布到库的模块版本列表。 除非你是包所有者，否则使用“删除”功能隐藏的包不会显示在版本历史记录中。

  • 项目网站 - 通过指定 ProjectURI，为模块清单的 PrivateData\PSData 部分中的模块提供项目网站。

  • 许可证 - 通过指定 LicenseURI，为模块清单的 PrivateData\PSData 部分中的模块提供许可证链接。

    重要

    如果未通过 LicenseURI 或在包内提供许可证，则 PowerShell 库的使用条款适用于该包。 有关详细信息，请参阅使用条款。

  • 图标 - 通过指定 IconURI，为模块清单的 PrivateData\PSData 部分中的模块提供链接。 URI 应指向具有透明背景的 85x85 图像。 URI 必须是图像文件的直接链接，不得转到网页或 PowerShell 库包中的文件。

以下列表显示由脚本文件中基于注释的元数据控制的 PowerShell 库包页 UI 的元素。

  • 标题 - 这是发布到库的包的名称

  • 版本 - 显示的版本是元数据中的版本字符串以及预发行版标签（如果已指定）。 该值来自元数据注释块中的 .VERSION 关键字。 发布预发行版脚本时，将预发行版字符串追加到版本。 有关在模块中指定预发行版字符串的信息，请参阅预发行版脚本版本。

  • 说明 - 此信息来自脚本文件的基于注释的帮助中的 .DESCRIPTION 关键字。

  • 要求接受许可证 - 脚本不支持许可证接受。 但是，支持其中的脚本依赖于需要接受许可证的模块的方案。 有关详细信息，请参阅要求接受脚本的许可证。

  • 发行说明 - 此信息来自脚本文件的基于注释的元数据中的 .RELEASENOTES 关键字。

  • 所有者 - 所有者是 PowerShell 库中可以更新包的用户列表。 所有者列表不包含在包清单中。 有关详细信息，请参阅管理项所有者。

  • 作者 - 此信息来自脚本文件的基于注释的元数据中的 .AUTHOR 关键字。 “作者”字段通常用于指定与包关联的公司或组织。

  • 版权 - 此信息来自脚本文件的基于注释的元数据中的 .COPYRIGHT 关键字。

  • 文件列表 - 将包发布到 PowerShell 库时会创建文件列表。 不可通过清单信息对其进行控制。 PowerShell 库创建显示在每个包的文件列表中的 .nuspec 文件。 此文件未随包一起安装在系统上。 这是对应包的 NuGet 包清单，可能会被忽略。

  • 标记 - *此信息来自脚本文件的基于注释的元数据中的 .TAGS 关键字。 标记具有特定要求和含义，这些内容将在标记详细信息部分中描述。

  • PowerShell 版本 - 对于专为 PowerShell 5.0 及更低版本设计的模块，使用“标记”对此进行控制。 对于桌面，使用标记 PSEdition_Desktop；对于核心，使用标记 PSEdition_Core。 对于专为 PowerShell 5.1 及更高版本设计的模块，清单中存在 CompatiblePSEditions 键。 有关详细信息，请参阅对模块的 PSEdition 支持。

  • 版本历史记录 - 显示已发布到库的模块版本列表。 除非你是包所有者，否则使用“删除”功能隐藏的包不会显示在版本历史记录中。

  • 项目网站 - 此信息来自脚本文件的基于注释的元数据中的 .PROJECTURI 关键字。

  • 许可证 - 此信息来自脚本文件的基于注释的元数据中的 .LICENSEURI 关键字。

    重要

    如果未通过 .LICENSEURI 或在包内提供许可证，则 PowerShell 库的使用条款适用于该包。 有关详细信息，请参阅使用条款。

  • 图标 - 此信息来自脚本文件的基于注释的元数据中的 .ICONURI 关键字。 URI 应指向具有透明背景的 85x85 图像。 URI 必须是图像文件的直接链接，不得转到网页或 PowerShell 库包中的文件。

编辑包详细信息

PowerShell 库编辑包页允许发行者更改为包显示的若干字段，具体为：

  • 标题
  • 说明
  • 总结
  • 图标 URL
  • 项目主页 URL
  • Authors
  • 版权信息
  • Tags
  • 发行说明
  • 需要许可证

应仅编辑库中的此信息，以更正较旧版本的模块显示的内容。 下载包的用户将看到元数据与 PowerShell 库不匹配。 每当更改库中的信息时，都应发布进行了相同更改的新版本的包。

标记详细信息

标记是使用者用来查找包的简单字符串。 标记在相关包中一致使用时最有价值。 使用同一个词的变体（例如 database 和 databases，或 test 和 testing）没有什么好处。 标记是单个词不区分大小写的字符串，并且不能包含空格。 如果存在你认为用户会搜索的短语，请将其添加到该包的说明中，以便可以在搜索结果中找到该短语。 使用 Pascal 大小写、连字符、下划线或句点来提高可读性。 谨慎创建长而复杂的异常标记，因为容易出现拼写错误。

PowerShell 库和 PowerShellGet cmdlet 对 PSEdition_Desktop 和 PSEdition_Core 标记具有特殊含义。 请参阅前面对“PowerShell 版本”的讨论。

如前面所述，标记在特定情况下发挥最大价值，并在许多包中一致使用。 作为发布者尝试找到要使用的最佳标记，最简单的方法是在 PowerShell 库中搜索你正在考虑的标记。 理想情况下，返回的包与你使用的该关键字一致。

下表显示了一些最常用的标记。 首选标记应返回最佳搜索结果。

首选标记 可选标记和备注
ActiveDirectory 当前不会单独使用 AD
Appveyor
自动化
AWS
Azure
AzureAD
AzureAutomation
AzureRm 主要用于 AzureRM 模块
备份
构建
ChatOps
云
Color
配置
CrescendoBuilt 导出模块时，Crescendo 会自动添加此标记
数据库 Databases（复数）不太可取
DBA
部署 Deploy 某种程度上不太常用
DevOps
DNS
Docker
DSC DesiredStateConfiguration 太长，因此不够理想
DSCResource
DSCResourceKit
Excel
Exchange
防火墙
GIT
GitHub
Gitlab
Google
HTML
Hyper-V HyperV 很少用作标记
IaaS
IIS
Json
Linux
日志 Log 首选用作一件东西
日志记录 Logging 首选用作一项操作
MacOS
监视
MSI
网络 Networking 非常相似，不经常使用
Office365 拼写出 Office 是可取的。 O365 虽然更短，但不经常使用
PackageManagement
Pester
PoshBot
报表 Report 是一件东西
报表 Reporting 是一项操作，Report 是一件东西
ResourceManager “Arm”是用来描述处理器组的，不得用于 Azure 资源管理器
REST
安全性 Defense 不太精确
SharePoint
SQL
SQLServer
存储
测试 Testing 不太可取
VersionControl Version 不太精确，但使用更频繁
VSTS
Windows
WinRM
WMI
Zip