about_Scripts

Descrição breve

Descreve como executar e gravar scripts no PowerShell.

Descrição longa

Um script é um arquivo de texto sem formatação que contém um ou mais comandos do PowerShell. Os scripts do PowerShell têm uma .ps1 extensão de arquivo.

Executar um script é muito parecido com a execução de um cmdlet. Digite o caminho e o nome do arquivo do script e use parâmetros para enviar dados e definir opções. Você pode executar scripts em seu computador ou em uma sessão remota em um computador diferente.

Escrever um script salva um comando para uso posterior e facilita o compartilhamento com outras pessoas. O mais importante é que ele permite executar os comandos simplesmente digitando o caminho do script e o nome do arquivo. Os scripts podem ser tão simples quanto um único comando em um arquivo ou tão extenso quanto um programa complexo.

Os scripts têm recursos adicionais, como o #Requires comentário especial, o uso de parâmetros, o suporte para seções de dados e a assinatura digital para segurança. Você também pode escrever tópicos de Ajuda para scripts e para quaisquer funções no script.

Como executar um script

Antes de executar um script no Windows, você precisa alterar a política de execução padrão do PowerShell. A política de execução não se aplica ao PowerShell em execução em plataformas não Windows.

A política Restrictedde execução padrão impede que todos os scripts sejam executados, incluindo scripts que você escreve no computador local. Para obter mais informações, consulte about_Execution_Policies.

A política de execução é salva no registro, portanto, você precisa alterá-la apenas uma vez em cada computador.

Para alterar a política de execução, use o procedimento a seguir.

No prompt de comando, digite:

Set-ExecutionPolicy AllSigned

ou

Set-ExecutionPolicy RemoteSigned

A alteração tem efeito imediato.

Para executar um script, digite o nome completo e o caminho completo para o arquivo de script.

Por exemplo, para executar o script Get-ServiceLog.ps1 no diretório C:\Scripts, digite:

C:\Scripts\Get-ServiceLog.ps1

Para executar um script no diretório atual, digite o caminho para o diretório atual ou use um ponto para representar o diretório atual, seguido por uma barra invertida de caminho (.\).

Por exemplo, para executar o script ServicesLog.ps1 no diretório local, digite:

.\Get-ServiceLog.ps1

Se o script tiver parâmetros, digite os parâmetros e os valores de parâmetro após o nome do arquivo de script.

Por exemplo, o comando a seguir usa o parâmetro ServiceName do script Get-ServiceLog para solicitar um log da atividade do serviço WinRM.

.\Get-ServiceLog.ps1 -ServiceName WinRM

Como um recurso de segurança, o PowerShell não executa scripts quando você clica duas vezes no ícone de script no Explorador de Arquivos ou quando digita o nome do script sem um caminho completo, mesmo quando o script está no diretório atual. Para obter mais informações sobre como executar comandos e scripts no PowerShell, consulte about_Command_Precedence.

Executar com o PowerShell

A partir do PowerShell 3.0, você pode executar scripts de Explorador de Arquivos.

Para usar o recurso "Executar com o PowerShell":

Execute Explorador de Arquivos, clique com o botão direito do mouse no nome do arquivo de script e selecione "Executar com o PowerShell".

O recurso "Executar com o PowerShell" foi projetado para executar scripts que não têm parâmetros necessários e não retornam a saída para o prompt de comando.

Para obter mais informações, consulte about_Run_With_PowerShell.

Executando scripts em outros computadores

Para executar um script em um ou mais computadores remotos, use o parâmetro FilePath do Invoke-Command cmdlet.

Insira o caminho e o nome do arquivo do script como o valor do parâmetro FilePath . O script deve residir no computador local ou em um diretório que o computador local possa acessar.

O comando a seguir executa o Get-ServiceLog.ps1 script nos computadores remotos chamados Server01 e Server02.

Invoke-Command -ComputerName Server01,Server02 -FilePath `
  C:\Scripts\Get-ServiceLog.ps1

Obter ajuda para scripts

O cmdlet Get-Help obtém os tópicos de ajuda para scripts, bem como para cmdlets e outros tipos de comandos. Para obter o tópico de ajuda para um script, digite Get-Help seguido pelo caminho e nome do arquivo do script. Se o caminho do script estiver em sua Path variável de ambiente, você poderá omitir o caminho.

Por exemplo, para obter ajuda para o script ServicesLog.ps1, digite:

get-help C:\admin\scripts\ServicesLog.ps1

Como escrever um script

Um script pode conter comandos válidos do PowerShell, incluindo comandos individuais, comandos que usam o pipeline, as funções e as estruturas de controle, como instruções If e Loops For.

Para escrever um script, abra um novo arquivo em um editor de texto, digite os comandos e salve-os em um arquivo com um nome de arquivo válido com a extensão de .ps1 arquivo.

O exemplo a seguir é um script simples que obtém os serviços que estão em execução no sistema atual e os salva em um arquivo de log. O nome do arquivo de log é criado a partir da data atual.

$date = (get-date).dayofyear
get-service | out-file "$date.log"

Para criar esse script, abra um editor de texto ou um editor de script, digite esses comandos e salve-os em um arquivo chamado ServiceLog.ps1.

Parâmetros em scripts

Para definir parâmetros em um script, use uma instrução Param. A Param instrução deve ser a primeira instrução em um script, exceto para comentários e quaisquer #Require instruções.

Os parâmetros de script funcionam como parâmetros de função. Os valores de parâmetro estão disponíveis para todos os comandos no script. Todos os recursos de parâmetros de função, incluindo o atributo Parameter e seus argumentos nomeados, também são válidos em scripts.

Ao executar o script, os usuários de script digitam os parâmetros após o nome do script.

O exemplo a seguir mostra um Test-Remote.ps1 script que tem um parâmetro ComputerName . Ambas as funções de script podem acessar o valor do parâmetro ComputerName .

param ($ComputerName = $(throw "ComputerName parameter is required."))

function CanPing {
   $error.clear()
   $tmp = test-connection $computername -erroraction SilentlyContinue

   if (!$?)
       {write-host "Ping failed: $ComputerName."; return $false}
   else
       {write-host "Ping succeeded: $ComputerName"; return $true}
}

function CanRemote {
    $s = new-pssession $computername -erroraction SilentlyContinue

    if ($s -is [System.Management.Automation.Runspaces.PSSession])
        {write-host "Remote test succeeded: $ComputerName."}
    else
        {write-host "Remote test failed: $ComputerName."}
}

if (CanPing $computername) {CanRemote $computername}

Para executar esse script, digite o nome do parâmetro após o nome do script. Por exemplo:

C:\PS> .\test-remote.ps1 -computername Server01

Ping succeeded: Server01
Remote test failed: Server01

Para obter mais informações sobre a instrução Param e os parâmetros de função, consulte about_Functions e about_Functions_Advanced_Parameters.

Escrever ajuda para scripts

Você pode escrever um tópico de ajuda para um script usando um dos dois métodos a seguir:

  • ajuda Comment-Based para scripts

    Crie um tópico da Ajuda usando palavras-chave especiais nos comentários. Para criar ajuda baseada em comentários para um script, os comentários devem ser colocados no início ou no final do arquivo de script. Para obter mais informações sobre a Ajuda baseada em comentários, consulte about_Comment_Based_Help.

  • ajuda XML-Based para scripts

    Crie um tópico de Ajuda baseado em XML, como o tipo que normalmente é criado para cmdlets. A Ajuda baseada em XML será necessária se você estiver traduzindo tópicos da Ajuda para vários idiomas.

Para associar o script ao tópico da Ajuda baseada em XML, use o . Palavra-chave de comentário da Ajuda ExternalHelp. Para obter mais informações sobre a palavra-chave ExternalHelp, consulte about_Comment_Based_Help. Para obter mais informações sobre a ajuda baseada em XML, consulte Como escrever a Ajuda do Cmdlet.

Retornando um valor de saída

Por padrão, os scripts não retornam um status de saída quando o script termina. Você deve usar a exit instrução para retornar um código de saída de um script. Por padrão, a instrução exit retorna 0. Você pode fornecer um valor numérico para retornar um status de saída diferente. Um código de saída diferente de zero normalmente sinaliza uma falha.

No Windows, qualquer número entre [int]::MinValue e [int]::MaxValue é permitido.

No Unix, somente números positivos entre [byte]::MinValue (0) e [byte]::MaxValue (255) são permitidos. Um número negativo no intervalo de -1 transferência -255 é convertido automaticamente em um número positivo adicionando 256. Por exemplo, -2 é transformado em 254.

No PowerShell, a instrução exit define o valor da $LASTEXITCODE variável. No Shell de Comando do Windows (cmd.exe), a instrução de saída define o valor da variável de %ERRORLEVEL% ambiente.

Qualquer argumento que não seja numérico ou fora do intervalo específico da plataforma é traduzido para o valor de 0.

Escopo do script e fornecimento de ponto

Cada script é executado em seu próprio escopo. As funções, variáveis, aliases e unidades criadas no script só existem no escopo do script. Você não pode acessar esses itens ou seus valores no escopo em que o script é executado.

Para executar um script em um escopo diferente, você pode especificar um escopo, como Global ou Local, ou você pode dot source do script.

O recurso de fornecimento de ponto permite executar um script no escopo atual, em vez de no escopo do script. Quando você executa um script que tem origem de ponto, os comandos no script são executados como se você os tivesse digitado no prompt de comando. As funções, variáveis, aliases e unidades que o script cria são criadas no escopo no qual você está trabalhando. Após a execução do script, você pode usar os itens criados e acessar seus valores em sua sessão.

Para criar um script de origem, digite um ponto (.) e um espaço antes do caminho do script.

Por exemplo:

. C:\scripts\UtilityFunctions.ps1

ou

. .\UtilityFunctions.ps1

Após a execução do UtilityFunctions.ps1 script, as funções e variáveis que o script cria são adicionadas ao escopo atual.

Por exemplo, o UtilityFunctions.ps1 script cria a New-Profile função e a $ProfileName variável.

#In UtilityFunctions.ps1

function New-Profile
{
  Write-Host "Running New-Profile function"
  $profileName = split-path $profile -leaf

  if (test-path $profile)
    {write-error "Profile $profileName already exists on this computer."}
  else
    {new-item -type file -path $profile -force }
}

Se você executar o UtilityFunctions.ps1 script em seu próprio escopo de script, a New-Profile função e a $ProfileName variável existirão somente enquanto o script estiver em execução. Quando o script é encerrado, a função e a variável são removidas, conforme mostrado no exemplo a seguir.

C:\PS> .\UtilityFunctions.ps1

C:\PS> New-Profile
The term 'new-profile' is not recognized as a cmdlet, function, operable
program, or script file. Verify the term and try again.
At line:1 char:12
+ new-profile <<<<
   + CategoryInfo          : ObjectNotFound: (new-profile:String) [],
   + FullyQualifiedErrorId : CommandNotFoundException

C:\PS> $profileName
C:\PS>

Quando você faz a origem do script e o executa, o script cria a New-Profile função e a $ProfileName variável em sua sessão no escopo. Após a execução do script, você pode usar a New-Profile função em sua sessão, conforme mostrado no exemplo a seguir.

C:\PS> . .\UtilityFunctions.ps1

C:\PS> New-Profile

    Directory: C:\Users\juneb\Documents\WindowsPowerShell

    Mode    LastWriteTime     Length Name
    ----    -------------     ------ ----
    -a---   1/14/2009 3:08 PM      0 Microsoft.PowerShellISE_profile.ps1

C:\PS> $profileName
Microsoft.PowerShellISE_profile.ps1

Para obter mais informações sobre escopo, consulte about_Scopes.

Scripts em módulos

Um módulo é um conjunto de recursos relacionados do PowerShell que podem ser distribuídos como uma unidade. Você pode usar módulos para organizar seus scripts, funções e outros recursos. Você também pode usar módulos para distribuir seu código para outras pessoas e para obter código de fontes confiáveis.

Você pode incluir scripts em seus módulos ou criar um módulo de script, que é um módulo que consiste inteiramente ou principalmente em um script e recursos de suporte. Um módulo de script é apenas um script com uma extensão de arquivo .psm1.

Para obter mais informações sobre módulos, consulte about_Modules.

Outros recursos de script

O PowerShell tem muitos recursos úteis que você pode usar em scripts.

  • #Requires - Você pode usar uma #Requires instrução para impedir que um script seja executado sem módulos ou snap-ins especificados e uma versão especificada do PowerShell. Para obter mais informações, consulte about_Requires.

  • $PSCommandPath - Contém o caminho completo e o nome do script que está sendo executado. Esse parâmetro é válido em todos os scripts. Essa variável automática é introduzida no PowerShell 3.0.

  • $PSScriptRoot - Contém o diretório do qual um script está sendo executado. No PowerShell 2.0, essa variável é válida somente em módulos de script (.psm1). A partir do PowerShell 3.0, ele é válido em todos os scripts.

  • $MyInvocation - A $MyInvocation variável automática contém informações sobre o script atual, incluindo informações sobre como ele foi iniciado ou "invocado". Você pode usar essa variável e suas propriedades para obter informações sobre o script enquanto ele está em execução. Por exemplo, o $MyInvocation. A variável MyCommand.Path contém o caminho e o nome do arquivo do script. $MyInvocation. A linha contém o comando que iniciou o script, incluindo todos os parâmetros e valores.

    A partir do PowerShell 3.0, $MyInvocation tem duas novas propriedades que fornecem informações sobre o script que chamou ou invocou o script atual. Os valores dessas propriedades são preenchidos somente quando o invocador ou chamador é um script.

    • PSCommandPath contém o caminho completo e o nome do script que chamou ou invocou o script atual.

    • PSScriptRoot contém o diretório do script que chamou ou invocou o script atual.

    Ao contrário das $PSCommandPath variáveis e $PSScriptRoot automáticas, que contêm informações sobre o script atual, as propriedades PSCommandPath e PSScriptRoot da $MyInvocation variável contêm informações sobre o script que chamou o script atual.

  • Seções de dados – você pode usar a Data palavra-chave para separar dados da lógica em scripts. As seções de dados também podem facilitar a localização. Para obter mais informações, consulte about_Data_Sections e about_Script_Internationalization.

  • Assinatura de script – você pode adicionar uma assinatura digital a um script. Dependendo da política de execução, você pode usar assinaturas digitais para restringir a execução de scripts que podem incluir comandos não seguros. Para obter mais informações, consulte about_Execution_Policies e about_Signing.

Confira também