Sobre 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 executar 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. Mais importante, 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 de 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 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 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.
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.
Escrevendo ajuda para scripts
Você pode escrever um tópico de ajuda para um script usando um dos dois seguintes métodos:
Comment-Based Ajuda 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.
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 em 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 ajuda de 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 não 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 é convertido no valor de 0.
Escopo de 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 no qual o script é executado.
Para executar um script em um escopo diferente, você pode especificar um escopo, como Global ou Local, ou você pode criar o script de origem.
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 de 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. Depois que o script for executado, você poderá usar os itens criados e acessar seus valores em sua sessão.
Para fazer a origem de um script, 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. Depois que o script for executado, você poderá 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 o 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#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 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$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,
$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.