about_Requires

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

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>

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 5.1

-PSSnapin <PSSnapin-Name> [-Version <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 <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.

Por exemplo:

Exija que Hyper-V (versão 1.1 ou superior) esteja instalado.

#Requires -Modules @{ ModuleName="Hyper-V"; ModuleVersion="1.1" }

Requer que Hyper-V (apenas a versão 1.1) esteja instalada.

#Requires -Modules @{ ModuleName="Hyper-V"; RequiredVersion="1.1" }

Requer que Hyper-V (versão 1.1 ou inferior) esteja instalado.

#Requires -Modules @{ ModuleName="Hyper-V"; MaximumVersion="1.1" }

Requer que qualquer versão do PSScheduledJob e PSWorkflow, esteja instalada.

#Requires -Modules PSWorkflow, PSScheduledJob

Ao usar a RequiredVersion chave, verifique se a string de versão corresponde exatamente à string de versão que você deseja exigir.

Get-Module Hyper-V

ModuleType Version    Name     ExportedCommands
---------- -------    ----     ------------------
Binary     2.0.0.0    hyper-v  {Add-VMAssignableDevice, ...}

O exemplo a seguir falha porque 2.0.0 não corresponde exatamente a 2.0.0.0.

#Requires -Modules @{ ModuleName="Hyper-V"; RequiredVersion="2.0.0" }

-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

-ShellId

Especifica o shell que o script requer. 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 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 PSWorkflow
#Requires -Version 3
param
(
    [Parameter(Mandatory=$true)]
    [string[]]
    $Path
)
...

Consulte também

• about_Automatic_Variables
• about_Language_Keywords
• about_PSSnapins
• Get-PSSnapin