about_Requires
Breve descrição
Impede que um script seja executado sem os elementos necessários.
Descrição longa
A #Requires instrução impede a execução de um script, a menos que sejam cumpridos os pré-requisitos da versão, módulos (e versão) do PowerShell ou snap-ins (e versão) e da edição. Se os pré-requisitos não forem cumpridos, o PowerShell não executa o script nem fornece outras funcionalidades de runtime, como a conclusão do separador.
Syntax
#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 utilização
Um script pode incluir mais do que uma #Requires instrução. As #Requires instruções podem aparecer em qualquer linha num script.
Colocar uma #Requires instrução dentro de uma função NÃO limita o âmbito. Todas as #Requires instruções são sempre aplicadas globalmente e têm de ser cumpridas antes de o script poder ser executado.
Aviso
Embora uma #Requires instrução possa aparecer em qualquer linha num script, a sua posição num script não afeta a sequência da respetiva aplicação. O estado global que a #Requires instrução apresenta tem de ser cumprido antes da execução do script.
Exemplo:
Get-Module AzureRM.Netcore | Remove-Module
#Requires -Modules AzureRM.Netcore
Poderá 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 de ser cumprido antes mesmo de o script poder ser executado. Em seguida, a primeira linha do script invalidou o estado necessário.
Parâmetros
-Caminho da assemblagem <> | <. Especificação da assemblagem NET>
Importante
A -Assembly sintaxe foi preterida. Não serve nenhuma função. A sintaxe foi adicionada no PowerShell 5.1, mas o código de suporte nunca foi implementado. A sintaxe ainda é aceite para retrocompatibilidade.
Especifica o caminho para o ficheiro DLL de assemblagem ou um nome de assemblagem .NET. O parâmetro Assemblagem foi introduzido no PowerShell 5.0. Para obter mais informações sobre as assemblagens .NET, veja Nomes da assemblagem.
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 necessária para o script. Introduza um número de versão principal e um número de versão secundária opcional.
Por exemplo:
#Requires -Version 6.0
-Modules <Module-Name> | < Tabela hash>
Especifica os módulos do PowerShell que o script necessita. Introduza 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 importa-os. Se os módulos não puderem ser importados, o PowerShell gera um erro de terminação.
Para cada módulo, escreva o nome do módulo (<Cadeia>) ou uma tabela hash. O valor pode ser uma combinação de cadeias e tabelas hash. A tabela hash tem as seguintes chaves.
ModuleName- Necessá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 aceitável mínima 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. Isto não pode ser utilizado com as outras chaves de Versão.
Nota
RequiredVersionfoi adicionado no Windows PowerShell 5.0.
MaximumVersionfoi adicionado no Windows PowerShell 5.1.
Por exemplo:
Exigir que AzureRM.Netcore (versão 0.12.0 ou superior) esteja instalada.
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; ModuleVersion="0.12.0" }
Exigir que AzureRM.Netcore (apenas a versão 0.12.0) esteja instalada.
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12.0" }
Requer que AzureRM.Netcore o (versão 0.12.0 ou menor) esteja instalado.
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; MaximumVersion="0.12.0" }
Exigir que qualquer versão de AzureRM.Netcore e PowerShellGet esteja instalada.
#Requires -Modules AzureRM.Netcore, PowerShellGet
Ao utilizar a chave, certifique-se de que a RequiredVersion cadeia de versão corresponde exatamente à cadeia 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 seguinte falha porque 0,12 não corresponde exatamente a 0.12.0.
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12" }
-PSEdition <PSEdition-Name>
Especifica uma edição do PowerShell que o script necessita. Os valores válidos são Core para PowerShell e Desktop para Windows PowerShell.
Por exemplo:
#Requires -PSEdition Core
-RunAsAdministrator
Quando este parâmetro de comutador é adicionado à sua #Requires instrução, especifica que a sessão do PowerShell na qual está a executar o script tem de ser iniciada com direitos de utilizador elevados. O parâmetro RunAsAdministrator é ignorado num sistema operativo não Windows. O parâmetro RunAsAdministrator foi introduzido no PowerShell 4.0.
Por exemplo:
#Requires -RunAsAdministrator
Exemplos
O script seguinte tem duas #Requires instruções. Se os requisitos especificados em ambas as instruções não forem cumpridos, o script não será executado. Cada #Requires instrução tem de ser o primeiro item numa linha:
#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0
Param
(
[parameter(Mandatory=$true)]
[String[]]
$Path
)
...