about_Scripts

Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0

TÓPICO

about_Scripts

DESCRIÇÃO BREVE

Descreve como executar e escrever 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 uma extensão de nome de arquivo .ps1.

A execução de um script é muito semelhante à execução de 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 o torna mais fácil de compartilhar 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 grandes como um programa complexo.

Os scripts têm recursos adicionais, como o comentário especial #Requires, o uso de parâmetros, suporte para seções de dados e 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 ser possível executar um script, você precisa alterar a política de execução padrão do Windows PowerShell. A política de execução padrão, "Restrita", impede que todos os scripts sejam executados, incluindo scripts escritos 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.

• 1. Inicie o Windows PowerShell com a opção "Executar como administrador".

• 2. No prompt de comando, digite:

              Set-ExecutionPolicy AllSigned
  

  - ou -

              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. Insira o corpo da seção aqui.

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 Windows PowerShell não executa scripts quando você clica duas vezes no ícone de script no Explorador de Arquivos ou quando você digita o nome do script sem um caminho completo, mesmo quando o script está no diretório atual. Para obter mais informações a execução de comandos e scripts no Windows PowerShell, consulte about_Command_Precedence.

EXECUTAR COM O POWERSHELL

A partir do Windows PowerShell 3.0, você pode executar scripts do Explorador de Arquivos (ou Windows Explorer, em versões anteriores do Windows).

Para usar o recurso "Executar com PowerShell":

No Explorador de arquivos (ou no Windows Explorer), clique com o botão direito do mouse no nome do arquivo de script e, em seguida, selecione "Executar com PowerShell".

O recurso "Executar com PowerShell" foi projetado para executar scripts que não possuem os parâmetros necessários e retorna a saída ao prompt de comando.

Para obter mais informações, consulte about_Run_With_PowerShell

EXECUÇÃO DE 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 nome de 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 pode acessar.

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

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

OBTER AJUDA SOBRE SCRIPTS

O cmdlet Get-Help obtém os tópicos da ajuda para scripts, bem como para outros tipos de comandos e cmdlets. Para obter o tópico da ajuda para um script, digite "Get-Help" seguido pelo nome de arquivo e caminho do script. Se o caminho do script estiver na variável de ambiente Path, você pode 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 qualquer comando válido do Windows 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, 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 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, em seguida, salve-os em um arquivo denominado 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, com exceção de comentários e quaisquer instruções #Requires.

Os parâmetros do 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 script Test-Remote.ps1 que tem um parâmetro ComputerName. As duas 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 A AJUDA PARA SCRIPTS

Você pode escrever um tópico da ajuda para um script usando qualquer 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 fim 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 os cmdlets. A Ajuda baseada em XML é necessária se você estiver traduzindo tópicos da Ajuda em vários idiomas.

  Para associar o script ao tópico da Ajuda baseado em XML, use a 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 "How to Write Cmdlet Help" (Como escrever a ajuda do cmdlet) na biblioteca MSDN (Microsoft Developer Network) em https://go.microsoft.com/fwlink/?LinkID=123415.

ESCOPO DO SCRIPT E DOT SOURCING

Cada script é executado em seu próprio escopo. As funções, variáveis, aliases e unidades que são criadas no script existem somente 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 pode realizar o dot sourcing do script. Insira o corpo da seção aqui.

O recurso de dot sourcing permite que você execute um script no escopo atual em vez de no escopo do script. Quando você executa um script que tem dot sourcing, 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 é executado, você pode usar os itens criados e acessar seus valores em sua sessão.

Para realizar o dot sourcing de 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 é executado, 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 "There is already a $profileName profile on this computer."}
            else
       {new-item -type file -path $profile -force }
        }

Se você executa o script UtilityFunctions.ps1 em seu próprio escopo de script, a função New-Profile e a variável $ProfileName existem somente enquanto o script está sendo executado. 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ê realiza o dot sourcing do 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 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 do Windows PowerShell relacionados 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 os 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 pode criar um módulo de script, que é um módulo que é composto inteiramente ou principalmente por um script e recursos de suporte. Um módulo de script é simplesmente um script com uma extensão de nome de arquivo .psm1.

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

OUTROS RECURSOS DE SCRIPT

O Windows PowerShell tem diversos recursos úteis que podem ser usados em scripts.

• #Requires
  Você pode usar uma instrução #Requires para evitar 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.

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

• $PSScriptRoot
  Contém o diretório do qual um script está sendo executado. No Windows PowerShell 2.0, essa variável é válida apenas em módulos de script (.psm1). A partir do Windows PowerShell 3.0, ela é válida 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 é executado. Por exemplo, a variável $MyInvocation.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 Windows 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 o 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.

  Diferente 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 ou invocou o script atual.

• Seções de dados
  Você pode usar a palavra-chave Data para separar dados de lógica em scripts. As seções de dados também podem tornar a localização mais fácil. Para obter mais informações, consulte about_Data_Sections e about_Script_Localization.

• 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

about_Command_Precedence

about_Comment_Based_Help

about_Execution_Policies

about_Functions

about_Modules

about_Profiles

about_Requires

about_Run_With_PowerShell

about_Scopes

about_Script_Blocks

about_Signing

Invoke-Command