Compartilhar via

about_Requires

Descrição curta

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 runtime, como a conclusão da guia.

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 para uso

Um script pode incluir mais de uma instrução #Requires. As instruções #Requires podem aparecer em qualquer linha em 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.

Aviso

Embora uma instrução #Requires possa aparecer em qualquer linha em 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 tinha que ser atendido antes que o script pudesse ser executado. Em seguida, a primeira linha do script invalidou o estado necessário.

Parâmetros

-Assembly <caminho do assembly> | <> de especificação de assembly do .NET

Importante

A sintaxe -Assembly foi preterida. Ele não serve para nenhuma função. A sintaxe foi adicionada ao 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 necessária para o script. 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 | <hashable>

Especifica os módulos do PowerShell necessários para o script. 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 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 um hashtable. O valor pode ser uma combinação de cadeias de caracteres e hashables. O hashtable 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 para 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.

Nota

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

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

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

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

Requer que AzureRM.Netcore (versão 0.12.0 ou menor) esteja instalada.

#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 chave 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-Nome>

Especifica uma edição do PowerShell que o script requer. Os valores válidos são Core para o PowerShell e Desktop para Windows PowerShell.

Por exemplo:

#Requires -PSEdition Core

-RunAsAdministrator

Quando esse parâmetro de comutador é 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 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 instruções #Requires. Se os requisitos especificados em ambas as instruções não forem atendidos, o script não será executado. Cada instrução #Requires deve ser o primeiro item em uma linha:

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

Consulte também

  • Last updated on