Bem-vindo à aula sobre scripts PowerShell (.ps1). Até agora, você provavelmente executou comandos diretamente no console, mas scripts são essenciais para automatizar tarefas, reutilizar código e criar ferramentas complexas. Nesta aula, você aprenderá a estrutura básica de um script, como executá-lo com segurança, como passar argumentos e como documentar seu código com comentários.

Vamos explorar desde a criação de um arquivo .ps1 simples até scripts mais elaborados com parâmetros e boas práticas. Ao final, você terá uma base sólida para desenvolver seus próprios scripts.

Estrutura

Um script PowerShell é um arquivo de texto com extensão .ps1 que contém uma sequência de comandos. Ele pode incluir variáveis, funções, estruturas de controle (if, for, etc.) e chamadas a cmdlets. A estrutura básica é simples: você escreve os comandos na ordem em que deseja que sejam executados, um por linha ou separados por ponto e vírgula.

Porém, para scripts robustos, é comum declarar parâmetros no início, definir variáveis, incluir funções e, por fim, a lógica principal. Um script bem estruturado facilita a manutenção e a depuração. Veja um exemplo de estrutura típica:

# Script de exemplo: estrutura básica

param(
    [string]$Nome
)

# Variáveis e configurações
$pastaDestino = "C:\Temp"

# Funções
function Saudacao {
    param($nome)
    Write-Host "Olá, $nome!"
}

# Lógica principal
if ($Nome) {
    Saudacao -nome $Nome
} else {
    Write-Host "Nenhum nome fornecido."
}

A estrutura acima mostra: a declaração de parâmetros, variáveis, definição de função e a lógica principal. Não há uma regra rígida, mas essa organização é recomendada para scripts maiores. Além disso, é importante usar indentação e nomes claros para melhorar a legibilidade.

Executando

Para executar um script .ps1, você pode chamá-lo a partir do console PowerShell, usando o caminho completo ou relativo. No entanto, por padrão, a política de execução do PowerShell pode bloquear scripts. Você precisa definir a política de execução para permitir scripts locais (por exemplo, RemoteSigned). Lembre-se de que alterar a política de execução requer privilégios administrativos.

Exemplo de execução:

# Definir política de execução (uma vez)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Executar script
.\meu_script.ps1

Se o script estiver no diretório atual, use .\ para indicar o caminho. Você também pode executar com a sintaxe & ".\meu_script.ps1" para tratar como um comando. Além disso, é possível executar um script diretamente pelo prompt, mas cuidado com espaços em branco no caminho: use aspas.

Outra forma é usar o operador de chamada & para executar um script a partir de uma variável ou string. Por exemplo:

$script = "C:\Scripts\meu_script.ps1"
& $script

Isso é útil quando você precisa executar scripts dinamicamente. Além disso, você pode passar argumentos na linha de comando, como veremos a seguir.

Argumentos

Scripts frequentemente precisam de entradas do usuário ou de parâmetros para serem flexíveis. No PowerShell, você define parâmetros usando a palavra-chave param no início do script. Cada parâmetro pode ter tipo, valor padrão e atributos como obrigatório.

Exemplo de script com parâmetros:

param(
    [Parameter(Mandatory=$true)]
    [string]$Nome,

    [int]$Idade = 30
)

Write-Host "Nome: $Nome, Idade: $Idade"

Para executar passando argumentos, você pode usar a sintaxe nomeada ou posicional:

# Nomeada
.\script.ps1 -Nome "Maria" -Idade 25

# Posicional (se a ordem for respeitada)
.\script.ps1 "Maria" 25

Se um parâmetro for obrigatório, o PowerShell solicitará o valor se não for fornecido. Você também pode usar ValueFromPipeline para receber entrada via pipeline, tornando o script mais integrado. Veja um exemplo:

param(
    [Parameter(ValueFromPipeline=$true)]
    [string]$Item
)

process {
    Write-Host "Processando: $Item"
}

Dessa forma, você pode canalizar objetos para o script: Get-ChildItem | .\script.ps1.

Além disso, você pode acessar argumentos não declarados usando a variável automática $args, mas é recomendado usar parâmetros para maior clareza e validação.

Comentários

Comentários são essenciais para documentar seu código e torná-lo compreensível para outras pessoas (ou para você mesmo no futuro). No PowerShell, existem dois tipos: comentários de linha e comentários de bloco.

Comentário de linha usa #:

# Isto é um comentário de linha
$var = 10  # comentário após o código

Comentário de bloco usa <# e #>:

<#
   Este é um comentário
   de múltiplas linhas.
#>

Além disso, o PowerShell suporta comentários baseados em ajuda (help comments) usando .SYNOPSIS, .DESCRIPTION, .PARAMETER, etc. Esses comentários são usados pelo cmdlet Get-Help para exibir informações sobre o script. Veja um exemplo:

<#
.SYNOPSIS
   Exemplo de script com ajuda.
.DESCRIPTION
   Este script demonstra o uso de comentários de ajuda.
.PARAMETER Nome
   O nome a ser usado.
.EXAMPLE
   .\script.ps1 -Nome "João"
#>
param([string]$Nome)
Write-Host "Olá, $Nome"

Para ver a ajuda, use Get-Help .\script.ps1. Isso é muito útil para criar scripts profissionais e auto-documentados.

Boas Práticas

Ao escrever scripts PowerShell, siga estas boas práticas: use nomes de variáveis e funções claros (verbo-substantivo para funções), declare parâmetros no início, evite aliases em scripts, use Write-Verbose para informações detalhadas, trate erros com try/catch e teste seu script com diferentes entradas. Além disso, mantenha seus scripts organizados em diretórios e use controle de versão.

Exercícios

  1. Exercício 1: Crie um script chamado saudacao.ps1 que peça o nome do usuário via parâmetro -Nome e exiba uma mensagem personalizada. Execute-o com o argumento "Ana".

    2. ✓ Resposta:
    # saudacao.ps1
param([string]$Nome)
Write-Host "Olá, $Nome! Bem-vindo ao PowerShell."

    Execute: .\saudacao.ps1 -Nome "Ana"

  2. Exercício 2: Escreva um script que receba dois números como parâmetros e exiba a soma. Inclua validação para garantir que são números.

    3. ✓ Resposta:
    param(
    [double]$Num1,
    [double]$Num2
)

$soma = $Num1 + $Num2
Write-Host "A soma é: $soma"

    Se quiser validar, use [ValidateScript()] ou verifique se o valor é numérico.

  3. Exercício 3: Crie um script que liste todos os arquivos de um diretório passado como parâmetro. Use o cmdlet Get-ChildItem e exiba o nome e o tamanho.

    4. ✓ Resposta:
    param(
    [string]$Caminho
)

$arquivos = Get-ChildItem -Path $Caminho -File
foreach ($arquivo in $arquivos) {
    Write-Host "$($arquivo.Name) - $($arquivo.Length) bytes"
}
  4. Exercício 4: Escreva um script que aceite uma lista de nomes via pipeline e exiba cada nome em maiúsculas.

    5. ✓ Resposta:
    param(
    [Parameter(ValueFromPipeline=$true)]
    [string]$Nome
)

process {
    Write-Host $Nome.ToUpper()
}
  5. Exercício 5: Crie um script com comentários de ajuda (SYNOPSIS, DESCRIPTION, PARAMETER) e verifique com Get-Help.

    6. ✓ Resposta:
    <#
.SYNOPSIS
   Exemplo de script com ajuda.
.DESCRIPTION
   Este script demonstra o uso de comentários de ajuda.
.PARAMETER Nome
   O nome a ser usado.
.EXAMPLE
   .\script.ps1 -Nome "João"
#>
param([string]$Nome)
Write-Host "Olá, $Nome"

    Depois, execute Get-Help .\script.ps1 para ver a ajuda.

Referências