about_Requires

Descrição curta

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 a versão, os módulos (e a versão) ou os snap-ins (e a versão) do PowerShell e os pré-requisitos de edição sejam atendidos. Se os pré-requisitos não forem atendidos, o PowerShell não executará o script.

Sintaxe

#Requires -Version <N>[.<n>]
#Requires -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
#Requires -Modules { <Module-Name> | <Hashtable> }
#Requires -PSEdition <PSEdition-Name>
#Requires -ShellId <ShellId> -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
#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 #Requires instrução 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.

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

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

-PSSnapin <PSSnapin-Name> [-Versão <N>[.<n>]]

Especifica um snap-in do PowerShell que o script exige. Insira o nome do snap-in e um número de versão opcional.

Por exemplo:

#Requires -PSSnapin DiskSnapin -Version 1.2

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

Para cada módulo, digite o nome do módulo (<String>) ou uma tabela de hash. O valor pode ser uma combinação de cadeias de caracteres e tabelas de hash. A tabela de 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 uma das três chaves abaixo. Essas chaves não podem ser usadas juntas.
  • ModuleVersion – especifica uma versão mínima aceitável do módulo.
  • RequiredVersion – especifica uma versão exata e necessária do módulo.
  • MaximumVersion – especifica a versão máxima aceitável do módulo.

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

-ShellId

Especifica o shell que o script exige. Insira o ID do shell. Se você usar o parâmetro ShellId , também deverá incluir o parâmetro PSSnapin . Você pode encontrar o ShellId atual consultando a $ShellId variável automática.

Por exemplo:

#Requires -ShellId MyLocalShell -PSSnapin Microsoft.PowerShell.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

• about_Automatic_Variables
• about_Language_Keywords