Acerca de requiereAbout Requires

Descripción breveShort description

Impide que un script se ejecute sin los elementos necesarios.Prevents a script from running without the required elements.

Descripción largaLong description

La #Requires instrucción impide que un script se ejecute a menos que se cumplan la versión de PowerShell, los módulos (y la versión), los complementos (y la versión) y los requisitos previos de la edición.The #Requires statement prevents a script from running unless the PowerShell version, modules (and version), or snap-ins (and version), and edition prerequisites are met. Si no se cumplen los requisitos previos, PowerShell no ejecuta el script.If the prerequisites aren't met, PowerShell doesn't run the script.

SintaxisSyntax

#Requires -Assembly { <Path to .dll> | <.NET assembly specification> }
#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.For more information about the syntax, see ScriptRequirements.

Reglas para su usoRules for use

Un script puede incluir más de una #Requires instrucción.A script can include more than one #Requires statement. Las #Requires instrucciones pueden aparecer en cualquier línea de un script.The #Requires statements can appear on any line in a script.

La colocación de una #Requires instrucción dentro de una función no limita su ámbito.Placing a #Requires statement inside a function does NOT limit its scope. Todas las #Requires instrucciones siempre se aplican globalmente y deben cumplirse antes de que se pueda ejecutar el script.All #Requires statements are always applied globally, and must be met, before the script can execute.

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.Even though a #Requires statement can appear on any line in a script, its position in a script does not affect the sequence of its application. El estado global que #Requires presenta la instrucción debe cumplirse antes de la ejecución del script.The global state the #Requires statement presents must be met before script execution.

Ejemplo:Example:

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

Podría pensar que el código anterior no debe ejecutarse porque el módulo necesario se quitó antes de la #Requires instrucción.You might think that the above code shouldn't run because the required module was removed before the #Requires statement. Sin embargo, el #Requires Estado tenía que cumplirse antes de que el script pudiera incluso ejecutarse.However, the #Requires state had to be met before the script could even execute. A continuación, la primera línea del script invalidó el Estado requerido.Then the first line of the script invalidated the required state.

ParámetrosParameters

-Assembly <Assembly path> |<.NET assembly specification>-Assembly <Assembly path> | <.NET assembly specification>

Especifica la ruta de acceso al archivo DLL de ensamblado o a un nombre de ensamblado .NET.Specifies the path to the assembly DLL file or a .NET assembly name. El parámetro Assembly se presentó en PowerShell 5,0.The Assembly parameter was introduced in PowerShell 5.0. Para obtener más información sobre los ensamblados .NET, vea nombres de ensamblados.For more information about .NET assemblies, see Assembly names.

Por ejemplo:For example:

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

-Version <N> [. <n> ]-Version <N>[.<n>]

Especifica la versión mínima de PowerShell que requiere el script.Specifies the minimum version of PowerShell that the script requires. Escriba un número de versión principal y un número de versión secundaria opcional.Enter a major version number and optional minor version number.

Por ejemplo:For example:

#Requires -Version 6.0

-PSSnapin <PSSnapin-Name> [-version <N> [. <n> ]]-PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]

Especifica un complemento de PowerShell que requiere el script.Specifies a PowerShell snap-in that the script requires. Escriba el nombre del complemento y un número de versión opcional.Enter the snap-in name and an optional version number.

Por ejemplo:For example:

#Requires -PSSnapin DiskSnapin -Version 1.2

-Módulos <Module-Name> |<Hashtable>-Modules <Module-Name> | <Hashtable>

Especifica los módulos de PowerShell que requiere el script.Specifies PowerShell modules that the script requires. Escriba el nombre del módulo y un número de versión opcional.Enter the module name and an optional version number.

Si los módulos necesarios no están en la sesión actual, PowerShell los importa.If the required modules aren't in the current session, PowerShell imports them. Si no se pueden importar los módulos, PowerShell genera un error de terminación.If the modules can't be imported, PowerShell throws a terminating error.

Para cada módulo, escriba el nombre del módulo ( <String> ) o una tabla hash.For each module, type the module name (<String>) or a hash table. El valor puede ser una combinación de cadenas y tablas hash.The value can be a combination of strings and hash tables. La tabla hash tiene las claves siguientes.The hash table has the following keys.

  • ModuleName - Requerido Especifica el nombre del módulo.ModuleName - Required Specifies the module name.
  • GUID - Opcional Especifica el GUID del módulo.GUID - Optional Specifies the GUID of the module.
  • También es necesario especificar una de las tres claves siguientes.It's also Required to specify one of the three below keys. Estas claves no se pueden usar juntas.These keys can't be used together.
    • ModuleVersion : Especifica una versión mínima aceptable del módulo.ModuleVersion - Specifies a minimum acceptable version of the module.
    • RequiredVersion : Especifica una versión exacta y necesaria del módulo.RequiredVersion - Specifies an exact, required version of the module.
    • MaximumVersion : Especifica la versión máxima aceptable del módulo.MaximumVersion - Specifies the maximum acceptable version of the module.

Nota

RequiredVersion se agregó en Windows PowerShell 5,0.RequiredVersion was added in Windows PowerShell 5.0. MaximumVersion se agregó en Windows PowerShell 5,1.MaximumVersion was added in Windows PowerShell 5.1.

Por ejemplo:For example:

Requiere que AzureRM.Netcore 0.12.0 esté instalado (versión o superior).Require that AzureRM.Netcore (version 0.12.0 or greater) is installed.

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

Requiere que AzureRM.Netcore ( solo versión 0.12.0 ) esté instalado.Require that AzureRM.Netcore ( only version 0.12.0) is installed.

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

Requiere que AzureRM.Netcore 0.12.0 se instale (versión o menos).Requires that AzureRM.Netcore (version 0.12.0 or lesser) is installed.

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

Requiere que esté instalada cualquier versión de AzureRM.Netcore y PowerShellGet .Require that any version of AzureRM.Netcore and PowerShellGet is installed.

#Requires -Modules AzureRM.Netcore, PowerShellGet

Cuando use la RequiredVersion clave, asegúrese de que la cadena de versión coincide exactamente con la cadena de versión que necesita.When using the RequiredVersion key, ensure your version string exactly matches the version string you require.

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.The following example fails because 0.12 doesn't exactly match 0.12.0.

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

-PSEdition <PSEdition-Name>-PSEdition <PSEdition-Name>

Especifica la edición de PowerShell que requiere el script.Specifies a PowerShell edition that the script requires. Los valores válidos son Core para PowerShell Core y Desktop para Windows PowerShell.Valid values are Core for PowerShell Core and Desktop for Windows PowerShell.

Por ejemplo:For example:

#Requires -PSEdition Core

-ShellId-ShellId

Especifica el shell que requiere el script.Specifies the shell that the script requires. Escriba el ID. de Shell.Enter the shell ID. Si usa el parámetro ShellId , también debe incluir el parámetro PSSnapin .If you use the ShellId parameter, you must also include the PSSnapin parameter. Puede buscar el ShellId actual consultando la $ShellId variable automática.You can find the current ShellId by querying the $ShellId automatic variable.

Por ejemplo:For example:

#Requires -ShellId MyLocalShell -PSSnapin Microsoft.PowerShell.Core

Nota

Este parámetro está pensado para su uso en mini shells, que han quedado en desuso.This parameter is intended for use in mini-shells, which have been deprecated.

-RunAsAdministrator-RunAsAdministrator

Cuando este parámetro de modificador se agrega a la #Requires instrucción, especifica que la sesión de PowerShell en la que se está ejecutando el script debe iniciarse con derechos de usuario elevados.When this switch parameter is added to your #Requires statement, it specifies that the PowerShell session in which you're running the script must be started with elevated user rights. El parámetro RunAsAdministrator se omite en un sistema operativo que no sea de Windows.The RunAsAdministrator parameter is ignored on a non-Windows operating system. El parámetro RunAsAdministrator se presentó en PowerShell 4,0.The RunAsAdministrator parameter was introduced in PowerShell 4.0.

Por ejemplo:For example:

#Requires -RunAsAdministrator

EjemplosExamples

El siguiente script tiene dos #Requires instrucciones.The following script has two #Requires statements. Si no se cumplen los requisitos especificados en ambas instrucciones, el script no se ejecuta.If the requirements specified in both statements aren't met, the script doesn't run. Cada #Requires instrucción debe ser el primer elemento de una línea:Each #Requires statement must be the first item on a line:

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

Consulte tambiénSee also

about_Automatic_Variablesabout_Automatic_Variables

about_Language_Keywordsabout_Language_Keywords