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
)
...
