Partilhar via

about_Requires

Breve descrição

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 preenchimento 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 utilização

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 #Requires 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 cumprido antes que o script pudesse sequer ser executado. Em seguida, a primeira linha do script invalidou o estado necessário.

Parâmetros

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

Importante

A -Assembly sintaxe foi preterida. Não tem qualquer função. 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>]

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 <Module-Name> | <Hashtable>

Especifica os módulos do PowerShell que o script requer. 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 importa. 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 strings 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 obrigatória do módulo. Isso não pode ser usado com as outras chaves de versão.

Nota

RequiredVersion foi adicionado no Windows PowerShell 5.0. MaximumVersion foi adicionado no 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 (apenas 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" }

Exija 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 que você precisa.

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

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 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 de uma linha:

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0
param
(
    [Parameter(Mandatory=$true)]
    [string[]]
    $Path
)
...

Consulte também