about_Scripts
Descrição breve
Descreve como executar e escrever 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 .ps1 arquivo.
Executar um script é muito parecido com executar um cmdlet. Você digita o caminho e o nome do arquivo do script e usa 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. Mais importante, ele permite que você execute 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 extensos quanto um programa complexo.
Os scripts têm recursos adicionais, como o #Requires comentário especial, o uso de parâmetros, suporte para seções de dados e assinatura digital para segurança.
Você também pode escrever tópicos da 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 sejam Windows.
A diretiva de execução padrão, Restricted, impede que todos os scripts sejam executados, incluindo scripts que você escreve no computador local. Para mais informações, veja about_Execution_Policies.
A diretiva de execução é salva no Registro, portanto, você precisa alterá-la apenas uma vez em cada computador.
Para alterar a diretiva de execução, use o procedimento a seguir.
No prompt de comando, digite:
Set-ExecutionPolicy AllSigned
or
Set-ExecutionPolicy RemoteSigned
A alteração entra em vigor 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 do script.
Por exemplo, o comando a seguir usa o parâmetro ServiceName do script Get-ServiceLog para solicitar um log da atividade de 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 do Explorador de Arquivos.
Para usar o recurso "Executar com PowerShell":
Execute o Explorador de Arquivos, clique com o botão direito do mouse no nome do arquivo do script e selecione "Executar com o PowerShell".
O recurso "Executar com 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 de um script, digite Get-Help seguido do caminho e do nome do arquivo do script. Se o caminho do script estiver na 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 quaisquer comandos válidos do PowerShell, incluindo comandos únicos, comandos que usam o pipeline, funções e 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 sendo executados 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 scripts, 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 declaraçõ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 dos 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 do 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.
Escrevendo ajuda para scripts
Você pode escrever um tópico de ajuda para um script usando um dos dois métodos a seguir:
Ajuda baseada em comentários para scripts
Crie um tópico da Ajuda usando palavras-chave especiais nos comentários. Para criar a 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 baseada em XML para scripts
Crie um tópico da Ajuda baseado em XML, como o tipo que normalmente é criado para cmdlets. A Ajuda baseada em XML é necessária se você estiver traduzindo tópicos da Ajuda para vários idiomas.
Para associar o script ao tópico da Ajuda baseado em XML, use o . Palavra-chave de comentário da Ajuda do 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 exit instrução 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, apenas números positivos entre [byte]::MinValue (0) e [byte]::MaxValue (255) são permitidos. Um número negativo no intervalo de até é -255 automaticamente traduzido -1 em um número positivo adicionando 256. Por exemplo, -2 é transformado em 254.
No PowerShell, a exit instrução define o $LASTEXITCODE valor da variável. No Shell de Comando do Windows (cmd.exe), a instrução exit define o %ERRORLEVEL% valor da variável de ambiente.
Qualquer argumento que não seja numérico ou esteja fora do intervalo específico da plataforma é convertido para o valor de 0.
Escopo de script e fornecimento de pontos
Cada script é executado em seu próprio escopo. As funções, variáveis, aliases e unidades criadas no script existem somente no escopo do script. Não é possível 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 pode apontar o código-fonte do 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 é dot sourced, 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 em que você está trabalhando. Depois que o script for executado, você poderá usar os itens criados e acessar seus valores em sua sessão.
Para apontar a origem de um script, digite um ponto (.) e um espaço antes do caminho do script.
Por exemplo:
. C:\scripts\UtilityFunctions.ps1
or
. .\UtilityFunctions.ps1
Depois que o UtilityFunctions.ps1 script é executado, 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ê pontua o código-fonte do script e o executa, o script cria a New-Profile função e a $ProfileName variável em sua sessão em seu escopo. Depois que o script é executado, 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 você pode criar um módulo de script, que é um módulo que consiste inteiramente ou principalmente de 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 do script
O PowerShell tem muitos recursos úteis que você pode usar em scripts.
#Requires- Você pode usar uma#Requiresinstruçã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 a partir 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$MyInvocationvariá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$MyInvocationarquivo . A variável MyCommand.Path contém o caminho e o nome do arquivo do script.$MyInvocation. Line contém o comando que iniciou o script, incluindo todos os parâmetros e valores.A partir do PowerShell 3.0,
$MyInvocationtem 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
$PSCommandPathvariáveis e$PSScriptRootautomáticas, que contêm informações sobre o script atual, as propriedades PSCommandPath e PSScriptRoot da$MyInvocationvariável contêm informações sobre o script que chamou o script atual.Seções de dados - Você pode usar a
Datapalavra-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.
