about_Requires
Descripción breve
Impide que un script se ejecute sin los elementos necesarios.
Descripción larga
La 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 o #Requires complementos (y versión). Si no se cumplen los requisitos previos, PowerShell no ejecuta el script.
Syntax
#Requires -Version <N>[.<n>]
#Requires -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
#Requires -Modules { <Module-Name> | <Hashtable> }
#Requires -PSEdition <PSEdition-Name>
#Requires -ShellId <ShellId> -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
#Requires -RunAsAdministrator
Para obtener más información sobre la sintaxis, vea ScriptRequirements.
Reglas de 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 #Requires colocación de una instrucción dentro de una función NO limita su ámbito. Todas #Requires las instrucciones siempre se aplican globalmente y deben cumplirse antes de que se pueda ejecutar el script.
Advertencia
Aunque una instrucción puede aparecer en cualquier línea de un script, su posición en un script no afecta #Requires a la secuencia de su aplicación. El estado global que presenta #Requires la 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, #Requires el 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 requerido.
Parámetros
-Assembly <Assembly path> |<.NET assembly specification>
Importante
La -Assembly sintaxis está en desuso. No sirve ninguna función. La sintaxis se agregó en PowerShell 5.1, pero el código compatible nunca se implementó. La sintaxis se sigue aceptando por compatibilidad con versiones anteriores.
Especifica la ruta de acceso al archivo DLL del ensamblado o un nombre de ensamblado .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"
-Version <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
-PSSnapin <PSSnapin-Name> [-Version <N> [. <n> ]]
Especifica un complemento de PowerShell que requiere el script. Escriba el nombre del complemento y un número de versión opcional.
Por ejemplo:
#Requires -PSSnapin DiskSnapin -Version 1.2
-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.
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 una de las tres claves siguientes. Estas claves no se pueden usar juntas.
ModuleVersion: especifica una versión mínima aceptable del módulo.RequiredVersion: especifica una versión exacta y necesaria del módulo.MaximumVersion: especifica la versión máxima aceptable del módulo.
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 superior) 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 AzureRM.Netcore cualquier versión de y PowerShellGet .
#Requires -Modules AzureRM.Netcore, PowerShellGet
Al usar la RequiredVersion clave, asegúrese de que la 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 Core y Desktop para Windows PowerShell.
Por ejemplo:
#Requires -PSEdition Core
-ShellId
Especifica el shell que requiere el script. Escriba el identificador del shell. Si usa el parámetro ShellId, también debe incluir el parámetro PSSnapin.
Puede encontrar el ShellId actual consultando la $ShellId variable automática.
Por ejemplo:
#Requires -ShellId MyLocalShell -PSSnapin Microsoft.PowerShell.Core
Nota
Este parámetro está pensado para su uso en mini shells, que han quedado en desuso.
-RunAsAdministrator
Cuando este parámetro switch se agrega a la instrucción , especifica que la sesión de PowerShell en la que se ejecuta el script debe iniciarse con derechos #Requires de usuario elevados. El parámetro RunAsAdministrator se omite en un sistema operativo que no es Windows. El parámetro RunAsAdministrator 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
)
...