Partilhar via

sobre_Requisitos

Breve descrição

Impede que um script seja executado sem os elementos necessários.

Descrição longa

A instrução #Requires 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 instrução #Requires. As instruções #Requires podem aparecer em qualquer linha de um script.

Colocar uma instrução #Requires dentro de uma função não limita seu escopo. Todas as instruções #Requires são sempre aplicadas globalmente e devem ser atendidas antes que o script possa ser executado.

Advertência

Embora uma instrução #Requires 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 #Requires 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 instrução #Requires. No entanto, o estado #Requires teve que ser cumprido antes que o script pudesse ser executado. Em seguida, a primeira linha do script invalidou o estado necessário.

Parâmetros

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

Importante

A sintaxe -Assembly 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 ficheiro DLL do assembly ou o nome de uma assembly .NET. O parâmetro Assembly foi introduzido no PowerShell 5.0. Para obter mais informações sobre assemblagens .NET, consulte Nomes de 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 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> | <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 instrução #Requires não carrega definições de classe e enumeração no módulo. Use a instrução using module 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 é Obrigató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 o 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 versão 0.12.0) esteja instalado.

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

Requer que o 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 tecla RequiredVersion, 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 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

-ExecutarComoAdministrador

Quando esse parâmetro switch é adicionado à instrução #Requires, 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 num sistema operativo não Windows. O parâmetro RunAsAdministrator foi introduzido no PowerShell 4.0.

Por exemplo:

#Requires -RunAsAdministrator

Exemplos

O script a seguir tem duas instruções #Requires. Se os requisitos especificados em ambas as instruções não forem atendidos, o script não será executado. Cada declaração #Requires 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

  • Last updated on