Tal vez hayas reunido algunas funciones grandes pero luchar para hacerlas cohesivas, intuitivas o compartibles. Sin una forma de definir la identidad y la funcionalidad de su módulo, administrar o escalar a medida que sus scripts evolucionan en herramientas robustas pueden ser un dolor de cabeza. No a menos que tenga un módulo manifiesto en su lugar.

Piense en un módulo manifiesto como la columna vertebral de su módulo PowerShell. En esta guía, aprenderá qué es un manifiesto y cómo crear uno que simplifique la gestión y mejore la usabilidad.

Requisitos previos

Para seguir con este tutorial, asegúrese de tener:

• PowerShell 5.1 o PowerShell 7+ instalado
• Acceso administrativo para crear archivos en el directorio de módulos PowerShell
• Un módulo básico de PowerShell (archivo .psm1) listo para mejorar con un manifiesto

¿Qué es un módulo de PowerShell manifiesto?

Un módulo manifiesto es un archivo de datos de PowerShell (.psd1) que contiene metadatos sobre su módulo. Es esencialmente un hashtable que le dice a PowerShell:

• Que funciona para exponer
• ¿Qué versiones de PowerShell son compatibles?
• Quien creó el módulo y cuando
• ¿Qué dependencias requiere el módulo?
• Cómo debe comportarse el módulo cuando se importa

Sin un manifiesto, los módulos de PowerShell todavía funcionan pero carecen de esmalte y control profesionales. El manifiesto transforma una colección de scripts en un paquete de versiones manejables.

Crear y nombrar un manifiesto

Un archivo manifiesto debe seguir convenciones de nomenclatura específicas. Nombra el archivo de manifiesto después de tu módulo con un .psd1 extensión. Por ejemplo, si se nombra su módulo Informeinventoryel archivo manifiesto debe ser ComputerInventory.PSD1.

Usando New-ModuleManifest

Mientras puede crear un manifiesto manualmente, el New-ModuleManifest Cmdlet simplifica el proceso. Aquí hay un ejemplo completo:

New-ModuleManifest -Path 'C:\Program Files\PowerShell\Modules\ComputerInventory\ComputerInventory.psd1' `
    -RootModule 'ComputerInventory.psm1' `
    -ModuleVersion '1.0.0' `
    -Guid (New-Guid).Guid `
    -Author 'Your Name' `
    -CompanyName 'Your Organization' `
    -Description 'A module for collecting computer hardware inventory information' `
    -PowerShellVersion '5.1' `
    -FunctionsToExport 'Get-MemoryInfo','Get-ProcessorInfo','Get-StorageInfo' `
    -CompatiblePSEditions 'Core','Desktop'

Comprender los parámetros

Camino – Dónde crear el archivo manifiesto. La ruta que se muestra utiliza la ubicación del módulo predeterminada de PowerShell, pero puede crear un manifiesto en cualquier lugar. Las ubicaciones comunes incluyen:

• C:\Program Files\PowerShell\Modules\ -Módulos de todo el sistema (requiere derechos de administrador)
• $HOME\Documents\PowerShell\Modules\ -Módulos específicos del usuario
• Cualquier carpeta de proyecto durante el desarrollo

Para ver todas las rutas del módulo PowerShell Búsquedas:

$env:PSModulePath -split ';'

Módulo raíz – El archivo principal .psm1 que contiene el código de su módulo. Este parámetro le dice a PowerShell qué archivo cargar cuando alguien importa su módulo. El camino es relativo a la ubicación manifiesta.

Se requieren parámetros opcionales requeridos

Solo el -Path El parámetro es obligatorio. New-ModuleManifest Crea un manifiesto de plantilla con valores predeterminados si omite otros parámetros. Sin embargo, estos parámetros son muy recomendados:

Explicaciones de parámetros clave:

• Guía: Un identificador único que distingue su módulo de los demás. (New-Guid).Guid genera un nuevo guía cada vez. Mantenga el mismo GUID en las versiones de su módulo.
• FunctionStoExport: Controles qué funciones están disponibles para los usuarios. Especifique los nombres de funciones exactos para ocultar las funciones de Helper y solo exponga su API pública.
• Compatibles: Declara qué ediciones PowerShell admite su módulo:
  • ‘Desktop’ = Windows PowerShell 5.1
  • ‘Core’ = PowerShell 7+
  • Ambos = funciona en cualquier edición
• Versión PowerShell: La versión mínima de PowerShell requerida. Establezca esto basado en los cmdlets y características que utiliza su módulo.

Explorar atributos clave en el manifiesto

Los manifiestos incluyen varios atributos que controlan el comportamiento del módulo. Aquí están los más importantes:

Atributos esenciales

Atributos de compatibilidad

Atributos de control de exportación

El FunctionsToExport El atributo merece atención especial. Por defecto, PowerShell exporta todas las funciones de un módulo. Esto puede exponer funciones auxiliares que pretendía mantener en privado.

# Export only public functions
FunctionsToExport = @('Get-MemoryInfo', 'Get-ProcessorInfo', 'Get-StorageInfo')

# This keeps ConvertTo-GB as an internal helper function

¿Por qué mantener las funciones privadas?

Hay varias razones para ocultar ciertas funciones de los usuarios del módulo:

1. Experiencia de usuario simplificada – Los usuarios solo ven las funciones principales que necesitan. Si su módulo tiene 3 funciones principales pero 15 funciones auxiliares, exponer todo crea confusión sobre qué usar.
2. Flexibilidad de implementación – Las funciones privadas se pueden cambiar, renombrar o eliminar sin romper el código que depende de su módulo. Las funciones públicas se convierten en parte del contrato de su módulo con los usuarios.
3. Evitar el mal uso – Las funciones auxiliares pueden requerir formatos de entrada específicos o asumir ciertas condiciones. El uso directo podría causar errores o un comportamiento inesperado.
4. Intellisense más limpio – Cuando los usuarios escriben el nombre de su módulo seguido de un tablero, solo ven los comandos relevantes, no en utilidades internas.

Por ejemplo, si ConvertTo-GB es un ayudante de cálculo simple utilizado por múltiples funciones, los usuarios no necesitan acceso directo a él. Deben usar las funciones principales que lo llaman internamente.

Para ver qué funciones se exportan realmente:

Get-Command -Module ComputerInventory

Gestión de dependencia

Los manifiestos también pueden administrar dependencias del módulo:

# Modules that must be imported before this module
RequiredModules = @('ActiveDirectory', 'Az.Compute')

# Assemblies that must be loaded
RequiredAssemblies = @('System.Web.dll')

# Scripts to run when module imports
ScriptsToProcess = @('Initialize-Module.ps1')

Prueba del manifiesto

Un manifiesto con errores de sintaxis o referencias faltantes causará fallas de importación de módulos. Valide siempre tu manifiesto usando Test-ModuleManifest:

Test-ModuleManifest -Path 'C:\Program Files\PowerShell\Modules\ComputerInventory\ComputerInventory.psd1'

Este cmdlet verifica:

• Errores de sintaxis en el archivo manifiesto
• Los archivos faltantes referenciados en el manifiesto
• Información de la versión inconsistente
• Valores de atributos no válidos

Si tiene éxito, devuelve un objeto PSModuleInfo. Si hay errores, proporciona mensajes de error detallados.

Problemas de validación comunes

Aquí hay problemas frecuentes Test-ModuleManifest captura:

1. Falta RootModule: El archivo .psm1 no existe en la ruta especificada
2. Formato de guía no válido: El GUID no está en el formato correcto
3. Errores de sintaxis: Comas faltantes, citas no cerradas o corchetes
4. Conflictos de versión: CompatiblePseditions especificadas sin PowerShellversion

Verificación del módulo

Después de crear y probar su manifiesto, verifique las cargas del módulo correctamente:

# Import the module
Import-Module ComputerInventory -Force

# Check module details
Get-Module -Name ComputerInventory | Format-List

# Verify exported functions
Get-Command -Module ComputerInventory

La salida debe mostrar:

• La versión del módulo correcto
• Comandos exportados esperados
• Tipo de módulo adecuado (script o binario)
• La ruta de instalación del módulo

Características manifiestas avanzadas

Sección de datos privado

El PrivateData La sección almacena metadatos adicionales, particularmente para la publicación de la galería de PowerShell:

PrivateData = @{
    PSData = @{
        Tags = @('Inventory', 'Hardware', 'Windows', 'CrossPlatform')
        LicenseUri = 'https://github.com/yourname/ComputerInventory/blob/main/LICENSE'
        ProjectUri = '<https://github.com/yourname/ComputerInventory>'
        IconUri = 'https://raw.githubusercontent.com/yourname/ComputerInventory/main/icon.png'
        ReleaseNotes="Initial release with basic hardware inventory functions"
    }
}

Inicialización del módulo

Usar ScriptsToProcess Para ejecutar el código de inicialización antes de que se cargue el módulo:

ScriptsToProcess = @('Init-ComputerInventory.ps1')

Este guión podría:

• Establecer variables con módulos
• Validar requisitos previos
• Configurar el registro
• Cargar archivos de configuración

Módulos anidados

Para módulos complejos, puede organizar el código en módulos anidados:

NestedModules = @(
    'Private\HelperFunctions.psm1',
    'Public\CoreFunctions.psm1'
)

Resumen

Has aprendido a crear módulos profesionales de PowerShell usando manifiestas. Un manifiesto bien elaborado transforma una colección de funciones en un módulo pulido y controlado por la versión que es fácil de compartir y mantener.

Control de llave:

• Crea siempre un manifiesto para los módulos que planeas compartir
• Usar New-ModuleManifest Para garantizar una estructura adecuada
• Prueba de manifiesto con Test-ModuleManifest Antes de distribución

Comience agregando un manifiesto a sus módulos existentes. A medida que obtiene experiencia, explore características avanzadas como módulos anidados y scripts de inicialización para construir herramientas de PowerShell cada vez más sofisticadas.