Valores de los metadatos de los paquetes que afectan a la interfaz de usuario de la Galería de PowerShell

  • Artículo

En este artículo se explica cómo se usan los metadatos en sus paquetes de la Galería de PowerShell. En el caso de los módulos, los metadatos se almacenan en el manifiesto del módulo. En el caso de los scripts, los metadatos se almacenan mediante palabras clave basadas en comentarios. Se usan los siguientes cmdlets para crear o actualizar estos metadatos:

En la lista siguiente se muestran los elementos de la interfaz de usuario de la página de los paquetes en la Galería de PowerShell que controla el manifiesto del módulo.

  • Título: el nombre del paquete publicado en la Galería.

  • Versión: la versión que se muestra es la cadena de versión de los metadatos y una etiqueta de la versión preliminar si está especificada. La cadena de versión preliminar especificada se anexa a ModuleVersion. Para obtener información sobre las cadenas de versión preliminar en los módulos, consulte Versiones preliminares de módulos.

  • Descripción: la descripción en el manifiesto del módulo.

  • Requerir aceptación de licencia: un módulo puede requerir que el usuario acepte una licencia modificando RequireLicenseAcceptance = $true, suministrando un LicenseURI y proporcionando un archivo license.txt en la raíz de la carpeta del módulo. Para obtener más información, consulte Requerir aceptación de licencia.

  • Notas de la versión: esta información procede de la sección ReleaseNotes, en PSData\PrivateData.

  • Propietarios: los propietarios son la lista de usuarios en Galería de PowerShell que pueden actualizar un paquete. La lista de propietarios no se incluye en el manifiesto del paquete. Hay documentación adicional que describe cómo administrar propietarios de elementos.

  • Autor: se incluye en el manifiesto del módulo como Author. El campo Autor a menudo se usa para especificar una empresa u organización asociada a un paquete.

  • Copyright: este es el campo Copyright del manifiesto del módulo.

  • FileList: la lista de archivos se crea cuando se publica el paquete en Galería de PowerShell. No se puede controlar mediante la información del manifiesto. Galería de PowerShell crea un archivo .nuspec que aparece en la lista de archivos de cada paquete. Este archivo no se instala con el paquete en un sistema. Es el manifiesto del paquete NuGet para el paquete y puede omitirse.

  • Etiquetas - las etiquetas se incluyen en PrivateData\PSData en el manifiesto del módulo. Las etiquetas tienen requisitos y significados específicos que se describen en la sección Detalles de las etiquetas.

  • Cmdlets: se proporcionan en el manifiesto del módulo con CmdletsToExport. Se recomienda enumerar explícitamente los nombres de cmdlet en lugar de usar el carácter comodín *. Tener una lista mejora el rendimiento del módulo de carga.

  • Funciones: se proporcionan en el manifiesto del módulo con FunctionsToExport. Se recomienda enumerar explícitamente los nombres de cmdlet en lugar de usar el carácter comodín *. Tener una lista mejora el rendimiento del módulo de carga.

  • Recursos de DSC: se incluyen en el manifiesto mediante DscResourcesToExport. Este valor solo se admite para los módulos de PowerShell 5.0 y versiones posteriores.

  • Funcionalidades de rol: los roles se muestran cuando el módulo tiene uno o varios archivos de funcionalidades de rol (.psrc). Estos archivos se usan en JEA. Para más información, consulte las funcionalidades de roles.

  • Ediciones de PowerShell: para los módulos diseñados para PowerShell 5.0 y versiones anteriores, se controlan mediante etiquetas. Para equipos de escritorio, utilice la etiqueta PSEdition_Desktop y para núcleos, utilice la etiqueta PSEdition_Core. Para módulos diseñados para PowerShell 5.1 y versiones posteriores, hay una clave CompatiblePSEditions en el manifiesto. Para obtener más información, consulte Compatibilidad de los módulos con PSEdition.

  • Dependencias: se incluyen en el manifiesto mediante RequiredModules.

  • Versión mínima de PowerShell: se proporciona en el manifiesto mediante PowerShellVersion.

  • Historial de versiones: muestra una lista de versiones del módulo que se han publicado en la Galería. Los paquetes ocultos mediante la característica Eliminar no se muestran en el historial de versiones a menos que usted sea el propietario del paquete.

  • Sitio del proyecto: el sitio del proyecto se proporciona para los módulos en la sección PrivateData\PSData del manifiesto del módulo al especificar un valor de ProjectURI.

  • Licencia: se proporciona un vínculo de licencia para los módulos en la sección PrivateData\PSData del manifiesto del módulo al especificar un valor de LicenseURI.

    Importante

    Si no se proporciona una licencia a través de LicenseURI o dentro del paquete, los Términos de uso para Galería de PowerShell se aplican al paquete. Para obtener más información, consulte los términos de uso.

  • Icono: se proporciona un vínculo para los módulos en la sección PrivateData\PSData del manifiesto del módulo al especificar un valor de IconURI. El URI debe apuntar a una imagen de 85 x85 con fondo transparente. El URI debe ser un vínculo directo al archivo de la imagen y no debe dirigir a una página web o un archivo en el paquete de Galería de PowerShell.

En la lista siguiente se muestran los elementos de la interfaz de usuario de la página de los paquetes en la Galería de PowerShell que controlan los metadatos basados en comentarios de un archivo de script.

  • Título: este es el nombre del paquete que se publica en la galería.

  • Versión: la versión que se muestra es la cadena de versión de los metadatos y una etiqueta de la versión preliminar si está especificada. El valor procede de la palabra clave .VERSION del bloque de comentarios de metadatos. Al publicar el script de la versión preliminar, anexe la cadena de versión preliminar a la versión. Para obtener información sobre cómo especificar cadenas de versión preliminar en módulos, consulte Versiones preliminares de scripts.

  • Descripción: esta información procede de la palabra clave .DESCRIPTION en la ayuda basada en comentarios de un archivo de script.

  • Requerir aceptación de licencia : no se admite la aceptación de licencia para scripts. Sin embargo, sí se admite el escenario en que un script depende de un módulo que requiere la aceptación de la licencia. Para obtener más información, consulte Requerir aceptación de licencia para scripts.

  • Notas de la versión: esta información procede de la palabra clave .RELEASENOTES en los metadatos basados en comentarios de un archivo de script.

  • Propietarios: los propietarios son la lista de usuarios en Galería de PowerShell que pueden actualizar un paquete. La lista de propietarios no se incluye en el manifiesto del paquete. Para más información, consulte Administrar propietarios de elementos.

  • Autor: esta información procede de la palabra clave .AUTHOR en los metadatos basados en comentarios de un archivo de script. El campo Autor a menudo se usa para especificar una empresa u organización asociada a un paquete.

  • Copyright: esta información procede de la palabra clave .COPYRIGHT en los metadatos basados en comentarios de un archivo de script.

  • FileList: la lista de archivos se crea cuando se publica el paquete en Galería de PowerShell. No se puede controlar mediante la información del manifiesto. Galería de PowerShell crea un archivo .nuspec que aparece en la lista de archivos de cada paquete. Este archivo no se instala con el paquete en un sistema. Es el manifiesto del paquete NuGet para el paquete y puede omitirse.

  • Etiquetas: *esta información procede de la palabra clave .TAGS en los metadatos basados en comentarios de un archivo de script. Las etiquetas tienen requisitos y significados específicos que se describen en la sección Detalles de las etiquetas.

  • Ediciones de PowerShell: para los módulos diseñados para PowerShell 5.0 y versiones anteriores, se controlan mediante etiquetas. Para equipos de escritorio, utilice la etiqueta PSEdition_Desktop y para núcleos, utilice la etiqueta PSEdition_Core. Para módulos diseñados para PowerShell 5.1 y versiones posteriores, hay una clave CompatiblePSEditions en el manifiesto. Para obtener más información, consulte Compatibilidad de los módulos con PSEdition.

  • Historial de versiones: muestra una lista de versiones del módulo que se han publicado en la Galería. Los paquetes ocultos mediante la característica Eliminar no se muestran en el historial de versiones a menos que usted sea el propietario del paquete.

  • Sitio del proyecto: esta información procede de la palabra clave .PROJECTURI en los metadatos basados en comentarios de un archivo de script.

  • Licencia: esta información procede de la palabra clave .LICENSEURI en los metadatos basados en comentarios de un archivo de script.

    Importante

    Si no se proporciona una licencia a través de .LICENSEURI o dentro del paquete, los Términos de uso para Galería de PowerShell se aplican al paquete. Para obtener más información, consulte los términos de uso.

  • Icono: esta información procede de la palabra clave .ICONURI en los metadatos basados en comentarios de un archivo de script. El URI debe apuntar a una imagen de 85 x85 con fondo transparente. El URI debe ser un vínculo directo al archivo de la imagen y no debe dirigir a una página web o un archivo en el paquete de Galería de PowerShell.

Edición de los detalles del paquete

La página Editar paquete de la Galería de PowerShell permite a los editores cambiar algunos de los campos que se muestran para un paquete, en concreto:

  • Título
  • Descripción
  • Resumen
  • URL del icono
  • URL de la página principal de proyecto
  • Authors
  • Copyright
  • Etiquetas
  • Notas de la versión
  • Se requiere licencia

Solo debe editar esta información en la Galería si necesita corregir lo que se muestra para una versión anterior de un módulo. Los usuarios que descarguen el paquete verán que los metadatos no coinciden con la información de Galería de PowerShell. Cada vez que cambie la información en la Galería, deberá publicar una nueva versión del paquete con los mismos cambios.

Detalles de las etiquetas

Las etiquetas son cadenas simples que se utilizan los consumidores para buscar paquetes. Las etiquetas son más valiosas cuando se usan de forma coherente en los paquetes relacionados. El uso de variaciones de la misma palabra (por ejemplo, base de datos y bases de datos, o prueba y pruebas) suele ofrecer pocas ventajas. Las etiquetas son cadenas de palabras únicas que no distinguen entre mayúsculas y minúsculas y que no pueden incluir espacios en blanco. Si hay una frase que cree que los usuarios van a buscar, agréguela a la descripción del paquete y se encontrará en los resultados de la búsqueda. Use combinaciones de mayúsculas y minúsculas de tipo Pascal, guiones, caracteres de subrayado o puntos para mejorar la legibilidad. Tenga cuidado al crear etiquetas largas, complejas y poco habituales, ya que frecuentemente se suelen escribir mal.

Los cmdlets de Galería de PowerShell y PowerShellGet tienen significados especiales para las etiquetas PSEdition_Desktop y PSEdition_Core. Consulte la explicación anterior de las ediciones de PowerShell.

Tal y como se mencionó antes, las etiquetas proporcionan el máximo valor cuando son específicas y muchos paquetes las usan de forma coherente. Como el editor siempre busca las mejores etiquetas para utilizar, el enfoque más sencillo es buscar en Galería de PowerShell las etiquetas que está considerando. Lo ideal es que los paquetes devueltos se alineen con el uso de esa palabra clave.

En la tabla siguiente se muestran algunas de las etiquetas más usadas. La etiqueta preferida debe devolver los mejores resultados de búsqueda.

Etiqueta preferida Alternativas y notas
ActiveDirectory AD no se utiliza por sí solo
Appveyor
Automatización
AWS
Azure
AzureAD
AzureAutomation
AzureRm Se utiliza principalmente para los módulos de AzureRM
Backup
Build
ChatOps
Nube
Color
Configuración
CrescendoBuilt Crescendo agrega automáticamente esta etiqueta al exportar el módulo
Base de datos Databases (en plural) es menos deseable
DBA
Implementación Deploy se utiliza con menos frecuencia
DevOps
DNS
Docker
DSC DesiredStateConfiguration es menos deseable; es demasiado largo.
DSCResource
DSCResourceKit
Excel
Exchange
Firewall
GIT
GitHub
Gitlab
Google
HTML
Hyper-V HyperV es menos común como etiqueta
IaaS
IIS
Json
Linux
Log Uso preferido de log como hecho
Registro Uso preferido de logging como acción
MacOS
Supervisión
MSI
Red Networking es similar, menos frecuente
Office365 Es preferible escribir Office completo. O365 es menos frecuente, aunque es más corto
PackageManagement
Pester
PoshBot
Informe Report es un objeto
Notificación Reporting es una acción, report es un objeto
ResourceManager "ARM" se utiliza para describir el grupo de procesadores y no debe usarse para Azure Resource Manager
REST
Seguridad Defense es menos preciso
SharePoint
SQL
SQLServer
Storage
Prueba Testing es menos deseable
VersionControl Version es menos preciso, aunque se utiliza con más frecuencia
VSTS
Windows
WinRM
WMI
Zip