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




Sumário