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 os pré-requisitos de versão, módulos (e versão) e 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 tempo de execução, como a conclusão de guias.

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 de 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

Embora uma #Requires instrução possa aparecer em qualquer linha de um script, sua posição em um script não afeta a sequência de seu aplicativo. O estado global que a instrução apresenta deve ser atendido antes da execução do #Requires 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 estado teve que ser cumprido #Requires antes que o script pudesse ser executado. Em seguida, a primeira linha do script invalidou o estado necessário.

Parâmetros

-Caminho> de montagem <| <. NET especificação de assembly>

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 .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ão>]

Especifica a versão mínima do PowerShell que o script requer. 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 <Module-Name> | <Tabela de hash>

Especifica os módulos do PowerShell que o script requer. Digite 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 lançará 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 hashtable. O valor pode ser uma combinação de cadeias de caracteres e hashtables. A hashtable 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 ao Windows PowerShell 5.0. MaximumVersion foi adicionado ao Windows PowerShell 5.1.

Por exemplo:

Exija que AzureRM.Netcore (versão 0.12.0 ou superior) esteja instalado.

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

Exija 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" }

Exigir que qualquer versão do AzureRM.Netcore e PowerShellGet esteja instalada.

#Requires -Modules AzureRM.Netcore, PowerShellGet

Ao usar a RequiredVersion chave, verifique se a cadeia de caracteres de versão corresponde exatamente à cadeia de caracteres 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 requer. Os valores válidos são Core para PowerShell e Desktop para Windows PowerShell.

Por exemplo:

#Requires -PSEdition Core

-RunAsAdministrator

Quando esse parâmetro de opção é 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 de uma linha:

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

Confira também