TÓPICO
about_Scripts
DESCRIÇÃO RESUMIDA
Descreve como gravar e executar scripts no Windows PowerShell.
DESCRIÇÃO LONGA
Um script é um arquivo de texto sem formatação que contém um ou
mais comandos do Windows PowerShell. Os scripts do Windows
PowerShell têm a extensão de nome de arquivo .ps1.
A gravação de um script salva um comando para uso posterior
e facilita seu compartilhamento com outras pessoas. E mais
importante, 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 comentário especial
#Requires, 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 funções no script.
COMO GRAVAR UM SCRIPT
Um script pode conter qualquer comando válido do Windows
PowerShell, inclusive comandos únicos, comandos que usam
o pipeline, funções e estruturas de controle, como instruções
If e loops For.
Para gravar um script, inicie um editor de texto (como o Bloco de
Notas) ou um editor de scripts (como o ISE (Ambiente de Script
Integrado) do Windows PowerShell). Digite os comandos e salve-os
em um arquivo com um nome de arquivo válido e a extensão de nome
de arquivo .ps1.
O exemplo a seguir é um script simples, que obtém os serviços 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 scripts, digite esses comandos e salve-os em um arquivo
denominado ServiceLog.ps1.
COMO EXECUTAR UM SCRIPT
Antes de poder executar um script, você precisa alterar a
diretiva de execução padrão do Windows PowerShell. A diretiva de
execução padrão, "Restricted", impede a execução de todos os
scripts, inclusive os gravados por você no computador local. Para
obter mais informações, consulte about_Execution_Policies.
Para executar um script, digite o nome completo e o caminho
completo para o arquivo do script.
Por exemplo, para executar o script ServicesLog no diretório
C:\Scripts, digite:
c:\scripts\ServicesLog.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:
.\ServicesLog.ps1
Por medida de segurança, o Windows PowerShell não executa scripts
quando você clica duas vezes no ícone do script no Windows
Explorer ou digita o nome do script sem um caminho completo,
mesmo que o script esteja no diretório atual. Para obter mais
informações sobre a execução de comandos e scripts no Windows
PowerShell, consulte about_Command_Precedence.
EXECUTANDO SCRIPTS REMOTAMENTE
Para executar um script em um computador remoto, use o parâmetro
FilePath do cmdlet Invoke-Command.
Digite o caminho e o nome do arquivo de script como o valor do
parâmetro FilePath. O script deve residir no computador local ou
em um diretório que o esse computador possa acessar.
O comando a seguir executa o script ServicesLog.ps1 no computador
remoto Server01.
invoke-command -computername Server01 -filepath
C:\scripts\servicesLog.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,
com a exceção de comentários e instruções #Requires.
Os parâmetros de script funcionam como parâmetros de função.
Os valores de parâmetros estão disponíveis para todos os comandos
no script. Todos os recursos dos parâmetros de função, inclusive
o atributo Parameter e seus argumentos nomeados, também são válidos
em scripts.
Ao executar o script, seus usuários digitam os parâmetros após
o nome do script.
O exemplo a seguir mostra um script Test-Remote.ps1 com um
parâmetro ComputerName. As duas funções do script podem acessar
o valor de parâmetro ComputerName.
param ($ComputerName = $(throw "O parâmetro ComputerName é obrigatório."))
function CanPing {
$error.clear()
$tmp = test-connection $computername -erroraction SilentlyContinue
if (!$?)
{write-host "Falha no ping: $ComputerName."; return $false}
else
{write-host "Ping bem-sucedido: $ComputerName"; return $true} }
function CanRemote {
$s = new-pssession $computername -erroraction SilentlyContinue
if ($s -is [System.Management.Automation.Runspaces.PSSession])
{write-host "Teste remoto bem-sucedido: $ComputerName."}
else
{write-host "Falha no teste remoto: $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 bem-sucedido: Server01
Falha no teste remoto: 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.
AJUDA PARA SCRIPTS
O cmdlet Get-Help obtém Ajuda para scripts, e também para
cmdlets, provedores e funções. Para obter Ajuda para um script,
digite Get-Help e o caminho e o nome de arquivo do script. Se o
caminho do script estiver na sua variável de ambiente Path, você
poderá omiti-lo.
Por exemplo, para obter Ajuda para o script ServicesLog.ps1, digite:
get-help C:\admin\scripts\ServicesLog.ps1
Você pode escrever a Ajuda para um script usando qualquer 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 a Ajuda baseada em comentários para
um script, é preciso colocar os comentários 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 para scripts baseada em XML
Crie um tópico da Ajuda baseada em XML, como o tipo 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 de 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 "How to Write Cmdlet
Help" na biblioteca do MSDN (Microsoft Developer Network) em
https://go.microsoft.com/fwlink/?LinkID=123415 (site em inglês).
ESCOPO DE SCRIPT E DOT SOURCING
Cada script é executado em seu próprio escopo. As funções,
variáveis, aliases e unidades criadas no script só existem no
escopo de script. Você não pode acessar esses itens, ou seus
valores, no escopo em que o script é executado.
Para executar um script em outro escopo, você pode especificar
um, como Global ou Local, ou usar dot sourcing no script.
O recurso de dot sourcing permite executar um script no escopo
atual, em vez de executá-lo no escopo de script. Quando você
executa um script com dot sourcing, os comandos do script são
executados como se você os tivesse digitado no prompt de comando.
As funções, as variáveis, os aliases e as unidades que o script
criar serão criados no escopo em que você estiver trabalhando.
Depois que o script for executado, você poderá usar os itens
criados e acessar seus valores na sua sessão.
Para usar dot sourcing em um script, digite um ponto (.) e um
espaço antes do caminho do script.
Por exemplo:
. C:\scripts\UtilityFunctions.ps1
-ou-
. .\UtilityFunctions.ps1
Depois que o script UtilityFunctions for executado, as funções
e as variáveis criadas por ele serão adicionadas ao escopo atual.
Por exemplo, o script UtilityFunctions.ps1 cria a função
New-Profile e a variável $ProfileName.
#Em UtilityFunctions.ps1
function New-Profile
{
Write-Host "Executando função New-Profile"
$profileName = split-path $profile -leaf
if (test-path $profile)
{write-error "Já existe um perfil $profileName neste computador."}
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
só existirão enquanto o script estiver em execução. Quando
o script fechar, a função e variável serão removidas, conforme
mostrado no exemplo a seguir.
C:\PS> .\UtilityFunctions.ps1
C:\PS> New-Profile
O termo 'new-profile' não é reconhecido como cmdlet, função,
programa operável ou arquivo de script. Verifique o termo
e tente novamente.
At line:1 char:12
+ new-profile <<<<
+ CategoryInfo : ObjectNotFound: (new-profile:String) [],
+ FullyQualifiedErrorId : CommandNotFoundException
C:\PS> $profileName
C:\PS>
Quando você usa dot sourcing no script e o executa, o script cria
a função New-Profile e a variável $ProfileName na sua sessão, no
seu escopo. Depois que o script é executado, você pode usar a função
New-Profile na sua sessão, conforme mostrado no exemplo a seguir.
C:\PS> . .\UtilityFunctions.ps1
C:\PS> New-Profile
Directory: C:\Users\mariag\Documents\WindowsPowerShell
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 14/1/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 Windows
PowerShell que podem ser distribuídos como uma unidade. Você pode
usar módulos para organizar seus scripts, funções e outros
recursos. Também é possível usar módulos para distribuir seu
código e obter código de fontes confiáveis.
Você pode incluir scripts em seus módulos ou criar um módulo de
script, que consiste totalmente ou principalmente em um script
e seus recursos de suporte. Um módulo de script é simplesmente um
script com extensão de nome de arquivo .psm1.
Para obter mais informações sobre módulos, consulte about_Modules.
OUTROS RECURSOS DE SCRIPTS
O Windows PowerShell tem muitos recursos úteis que você pode
aplicar aos 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 Windows PowerShell. Para obter
mais informações, consulte about_Requires.
$MyInvocation
A variável automática $MyInvocation contém informações sobre
o comando atual, o que inclui o script atual. Você pode usar
essa variável e suas propriedades para obter informações
sobre o script enquanto ele estiver em execução. Por exemplo,
a variável $MyInvocation.MyCommand.Path contém o caminho e o
nome de arquivo de script.
Seções de dados
Você pode usar a palavra-chave Data para separar os dados da
lógica nos 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_Localization.
Assinatura de scripts
Você pode acrescentar uma assinatura digital a um script.
Dependendo da diretiva de execução, você pode usar
assinaturas digitais para restringir a execução de scripts
capazes de incluir comandos não seguros. Para obter mais
informações, consulte about_Execution_Policies e about_Signing.
CONSULTE TAMBÉM
about_Command_Precedence
about_Comment_Based_Help
about_Execution_Policies
about_Functions
about_Modules
about_Profiles
about_Requires
about_Scopes
about_Script_Blocks
about_Signing
Invoke-Command