about_Requires
Descrição breve
Impede que um script seja executado sem os elementos necessários.
Descrição longa
A #Requires instrução impede que um script seja executado, a menos que a versão, os módulos (e a versão) e os pré-requisitos de edição do PowerShell sejam atendidos. Se os pré-requisitos não forem atendidos, o PowerShell não executará o script nem fornecerá outros recursos de runtime, como preenchimento de tabulação.
Sintaxe
#Requires -Version <N>[.<n>]
#Requires -Modules { <Module-Name> | <Hashtable> }
#Requires -PSEdition <PSEdition-Name>
#Requires -RunAsAdministrator
Para obter mais informações sobre a sintaxe, consulte ScriptRequirements.
Regras de uso
Um script pode incluir mais de uma #Requires instrução. As #Requires instruções podem aparecer em qualquer linha em um script.
Colocar uma #Requires instrução dentro de uma função não limita seu escopo. Todas as #Requires instruções são sempre aplicadas globalmente e devem ser atendidas antes que o script possa ser executado.
Aviso
Mesmo que uma #Requires instrução possa aparecer em qualquer linha em um script, sua posição em um script não afeta a sequência de sua aplicação. O estado global que a #Requires instrução apresenta deve ser atendido antes da execução do script.
Exemplo:
Get-Module AzureRM.Netcore | Remove-Module
#Requires -Modules AzureRM.Netcore
Você pode pensar que o código acima não deve ser executado porque o módulo necessário foi removido antes da #Requires instrução. No entanto, o #Requires estado teve que ser atendido antes que o script pudesse ser executado. Em seguida, a primeira linha do script invalidou o estado necessário.
Parâmetros
-Caminho da <montagem> | <. NET>
Importante
A -Assembly sintaxe foi preterida. Não serve para nada. A sintaxe foi adicionada no PowerShell 5.1, mas o código de suporte nunca foi implementado. A sintaxe ainda é aceita para compatibilidade com versões anteriores.
Especifica o caminho para o arquivo DLL do assembly ou um nome de assembly do .NET. O parâmetro Assembly foi introduzido no PowerShell 5.0. Para obter mais informações sobre assemblies .NET, consulte Nomes de assembly.
Por exemplo:
#Requires -Assembly path\to\foo.dll
#Requires -Assembly "System.Management.Automation, Version=3.0.0.0,
Culture=neutral, PublicKeyToken=31bf3856ad364e35"
-Versão <N>[.<n>]
Especifica a versão mínima do PowerShell que o script exige. Insira um número de versão principal e um número de versão secundária opcional.
Por exemplo:
#Requires -Version 6.0
-Módulos <Nome> do Módulo | <Tabela de hash>
Especifica os módulos do PowerShell que o script exige. Insira o nome do módulo e um número de versão opcional.
Se os módulos necessários não estiverem na sessão atual, o PowerShell os importará. Se os módulos não puderem ser importados, o PowerShell gerará um erro de encerramento.
A #Requires instrução não carrega definições de classe e enumeração no módulo. Use a using module instrução no início do script para importar o módulo, incluindo as definições de classe e enumeração. Para obter mais informações, consulte about_Using.
Para cada módulo, digite o nome do módulo (<String>) ou uma tabela de hash. O valor pode ser uma combinação de strings e tabelas de hash. A tabela de hash tem as seguintes chaves.
-
ModuleName- Obrigatório Especifica o nome do módulo. -
GUID- Opcional Especifica o GUID do módulo. - Também é necessário especificar pelo menos uma das três chaves abaixo.
-
ModuleVersion- Especifica uma versão mínima aceitável do módulo. -
MaximumVersion- Especifica a versão máxima aceitável do módulo. -
RequiredVersion- Especifica uma versão exata e necessária do módulo. Isso não pode ser usado com as outras chaves de versão.
-
Observação
RequiredVersion foi adicionado no Windows PowerShell 5.0.
MaximumVersion foi adicionado no Windows PowerShell 5.1.
Por exemplo:
Requer que AzureRM.Netcore (versão 0.12.0 ou superior) esteja instalado.
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; ModuleVersion="0.12.0" }
Requer que AzureRM.Netcore (somente a versão 0.12.0) esteja instalada.
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12.0" }
Requer que AzureRM.Netcore (versão 0.12.0 ou inferior) esteja instalado.
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; MaximumVersion="0.12.0" }
Requer que qualquer versão do AzureRM.Netcore e PowerShellGet esteja instalada.
#Requires -Modules AzureRM.Netcore, PowerShellGet
Ao usar a RequiredVersion chave, verifique se a string de versão corresponde exatamente à string de versão necessária.
Get-Module AzureRM.Netcore -ListAvailable
Directory: /home/azureuser/.local/share/powershell/Modules
ModuleType Version Name PSEdition ExportedCommands
---------- ------- ---- --------- ----------------
Script 0.12.0 AzureRM.Netcore Core
O exemplo a seguir falha porque 0.12 não corresponde exatamente a 0.12.0.
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12" }
-PSEdition <PSEdition-Nome>
Especifica uma edição do PowerShell que o script exige. Os valores válidos são Core para PowerShell e Desktop para Windows PowerShell.
Por exemplo:
#Requires -PSEdition Core
-RunAsAdministrator
Quando esse parâmetro switch é adicionado à sua #Requires instrução, ele especifica que a sessão do PowerShell na qual você está executando o script deve ser iniciada com direitos de usuário elevados. O parâmetro RunAsAdministrator é ignorado em um sistema operacional não Windows. O parâmetro RunAsAdministrator foi introduzido no PowerShell 4.0.
Por exemplo:
#Requires -RunAsAdministrator
Exemplos
O script a seguir tem duas #Requires instruções. Se os requisitos especificados em ambas as instruções não forem atendidos, o script não será executado. Cada #Requires instrução deve ser o primeiro item em uma linha:
#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0
Param
(
[parameter(Mandatory=$true)]
[String[]]
$Path
)
...
