about_Requires

Descripción breve

Impide que un script se ejecute sin los elementos necesarios.

Descripción larga

La #Requires instrucción impide que se ejecute un script a menos que se cumplan los requisitos previos de edición, módulos y versiones de PowerShell. Si no se cumplen los requisitos previos, PowerShell no ejecuta el script ni proporciona otras características en tiempo de ejecución, como la finalización de tabulaciones.

Sintaxis

#Requires -Version <N>[.<n>]
#Requires -Modules { <Module-Name> | <Hashtable> }
#Requires -PSEdition <PSEdition-Name>
#Requires -RunAsAdministrator

Para obtener más información sobre la sintaxis, consulte ScriptRequirements.

Reglas para su uso

Un script puede incluir más de una #Requires instrucción. Las #Requires instrucciones pueden aparecer en cualquier línea de un script.

La colocación de una #Requires instrucción dentro de una función no limita su ámbito. Todas las #Requires instrucciones siempre se aplican globalmente y deben cumplirse antes de que se pueda ejecutar el script.

Advertencia

Aunque una #Requires instrucción puede aparecer en cualquier línea de un script, su posición en un script no afecta a la secuencia de su aplicación. El estado global que presenta la #Requires instrucción debe cumplirse antes de la ejecución del script.

Ejemplo:

Get-Module AzureRM.Netcore | Remove-Module
#Requires -Modules AzureRM.Netcore

Es posible que piense que el código anterior no debe ejecutarse porque el módulo necesario se quitó antes de la #Requires instrucción . Sin embargo, el #Requires estado tenía que cumplirse antes de que el script pudiera incluso ejecutarse. A continuación, la primera línea del script invalidó el estado necesario.

Parámetros

-Ruta de acceso> del ensamblado de ensamblado <| <. Especificación del ensamblado NET>

Importante

La -Assembly sintaxis está en desuso. No sirve ninguna función. La sintaxis se agregó en PowerShell 5.1, pero el código auxiliar nunca se implementó. La sintaxis todavía se acepta por motivos de compatibilidad con versiones anteriores.

Especifica la ruta de acceso al archivo DLL del ensamblado o un nombre de ensamblado de .NET. El parámetro Assembly se introdujo en PowerShell 5.0. Para obtener más información sobre los ensamblados de .NET, vea Nombres de ensamblado.

Por ejemplo:

#Requires -Assembly path\to\foo.dll
#Requires -Assembly "System.Management.Automation, Version=3.0.0.0,
  Culture=neutral, PublicKeyToken=31bf3856ad364e35"

-Versión <N>[.<n>]

Especifica la versión mínima de PowerShell que requiere el script. Escriba un número de versión principal y un número de versión secundaria opcional.

Por ejemplo:

#Requires -Version 6.0

-Modules <Module-Name> | <Hashtable>

Especifica los módulos de PowerShell que requiere el script. Escriba el nombre del módulo y un número de versión opcional.

Si los módulos necesarios no están en la sesión actual, PowerShell los importa. Si no se pueden importar los módulos, PowerShell produce un error de terminación.

La #Requires instrucción no carga definiciones de clase y enumeración en el módulo. Use la using module instrucción al principio del script para importar el módulo, incluidas las definiciones de clase y enumeración. Para obtener más información, consulte about_Using.

Para cada módulo, escriba el nombre del módulo (<String>) o una tabla hash. El valor puede ser una combinación de cadenas y tablas hash. La tabla hash tiene las siguientes claves.

  • ModuleName - Obligatorio Especifica el nombre del módulo.
  • GUID - Opcional Especifica el GUID del módulo.
  • También es necesario especificar al menos una de las tres claves siguientes.
    • ModuleVersion : especifica una versión mínima aceptable del módulo.
    • MaximumVersion : especifica la versión máxima aceptable del módulo.
    • RequiredVersion : especifica una versión exacta y necesaria del módulo. Esto no se puede usar con las otras claves de versión.

Nota:

RequiredVersion se agregó en Windows PowerShell 5.0. MaximumVersion se agregó en Windows PowerShell 5.1.

Por ejemplo:

Requerir que AzureRM.Netcore (versión 0.12.0 o posterior) esté instalado.

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; ModuleVersion="0.12.0" }

Requerir que AzureRM.Netcore (solo versión 0.12.0) esté instalado.

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12.0" }

Requiere que AzureRM.Netcore (versión 0.12.0 o menor) esté instalado.

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; MaximumVersion="0.12.0" }

Requerir que se instale cualquier versión de AzureRM.Netcore y PowerShellGet .

#Requires -Modules AzureRM.Netcore, PowerShellGet

Al usar la clave, asegúrese de que la RequiredVersion cadena de versión coincide exactamente con la cadena de versión que necesita.

Get-Module AzureRM.Netcore -ListAvailable
    Directory: /home/azureuser/.local/share/powershell/Modules

ModuleType Version Name            PSEdition ExportedCommands
---------- ------- ----            --------- ----------------
Script     0.12.0  AzureRM.Netcore Core

En el ejemplo siguiente se produce un error porque 0.12 no coincide exactamente con 0.12.0.

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12" }

-PSEdition <PSEdition-Name>

Especifica una edición de PowerShell que requiere el script. Los valores válidos son Core para PowerShell y Escritorio para Windows PowerShell.

Por ejemplo:

#Requires -PSEdition Core

-RunAs Administración istrator

Cuando se agrega este parámetro switch a la #Requires instrucción , especifica que la sesión de PowerShell en la que se ejecuta el script debe iniciarse con derechos de usuario elevados. El parámetro RunAs Administración istrator se omite en un sistema operativo que no es Windows. El parámetro RunAs Administración istrator se introdujo en PowerShell 4.0.

Por ejemplo:

#Requires -RunAsAdministrator

Ejemplos

El siguiente script tiene dos #Requires instrucciones. Si no se cumplen los requisitos especificados en ambas instrucciones, el script no se ejecuta. Cada #Requires instrucción debe ser el primer elemento de una línea:

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0
Param
(
    [parameter(Mandatory=$true)]
    [String[]]
    $Path
)
...

Consulte también