about_Scripts

Descrição curta

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 extensão de arquivo .ps1.

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 comentário #Requires 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 que não são do Windows.

A política de execução padrão, Restricted, impede que todos os scripts sejam executados, incluindo scripts que você escreve no computador local. Para obter mais informações, consulte o item sobre Políticas de Execução.

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

Set-ExecutionPolicy RemoteSigned

A alteração é efetivada imediatamente.

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 de atividade de serviço do 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 no Explorador de Arquivos.

Para usar o recurso "Executar com o PowerShell":

Execute o 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 cmdlet Invoke-Command.

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 script Get-ServiceLog.ps1 nos computadores remotos denominado Server01 e Server02.

$invokeCommandSplat = @{
    ComputerName = 'Server01', 'Server02'
    FilePath = 'C:\Scripts\Get-ServiceLog.ps1'
}
Invoke-Command @invokeCommandSplat

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 de um script, digite Get-Help seguido pelo caminho e nome do arquivo do script. Se o caminho do script estiver na sua variável de ambiente PATH, 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 de 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 arquivo .ps1.

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 instrução param deve ser a primeira instrução em um script, exceto para comentários e quaisquer instruções #Requires.

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 script Test-Remote.ps1 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 para scripts baseada em comentários

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.
XML-Based Ajuda 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 a palavra-chave de comentário da Ajuda .EXTERNALHELP. Para obter mais informações, consulte:

about_Comment_Based_Help
como escrever de ajuda do cmdlet

Retornar 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 instrução exit 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 até -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 variável $LASTEXITCODE. No Shell de Comando do Windows (cmd.exe), a instrução exit define o valor da variável de ambiente %ERRORLEVEL%.

Qualquer argumento não 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 que são criados no script só existem no escopo do script. Você não pode acessar esses itens ou seus valores no escopo no qual o script é executado.

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

O recurso dot sourcing permite executar um script no escopo atual, em vez de no escopo do script. Quando você executa um script que é referenciado com 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 drives que o script cria são criados no escopo em que 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 fazer o dot source de um script, digite um ponto (.) e um espaço antes do caminho do script.

Por exemplo:

. C:\scripts\UtilityFunctions.ps1

. .\UtilityFunctions.ps1

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

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

#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 script UtilityFunctions.ps1 em seu próprio escopo de script, a função New-Profile e a variável $ProfileName 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>

Ao fazer o dot source script e executá-lo, o script cria a função New-Profile e a variável $ProfileName na sua sessão em seu escopo. Após a execução do script, você pode usar a função New-Profile 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 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 instrução #Requires para impedir que um script seja executado sem módulos ou snap-ins especificados e uma versão especificada do PowerShell. Para saber mais, 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 variável automática $MyInvocation 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, a variável $MyInvocation.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 variáveis automáticas $PSCommandPath e $PSScriptRoot, que contêm informações sobre o script atual, as propriedades PSCommandPath e PSScriptRoot da variável $MyInvocation contêm informações sobre o script que chamou o script atual.
Seções de dados – você pode usar a palavra-chave Data 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 sobre Secções de Dados e sobre Internacionalização de Script.
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.

Consulte também

Comentários

Esta página foi útil?

Last updated on 2025-09-24