Compartilhar via

Como escrever um módulo de script do Windows PowerShell

Um módulo de script é qualquer script válido do PowerShell salvo em uma extensão de .psm1. Essa extensão permite que o mecanismo do PowerShell use regras e cmdlets de módulo em seu arquivo. A maioria desses recursos está lá para ajudá-lo a instalar seu código em outros sistemas, bem como gerenciar o escopo. Você também pode usar um arquivo de manifesto de módulo, que descreve instalações e soluções mais complexas.

Escrevendo um módulo de script do PowerShell

Para criar um módulo de script, salve um script válido do PowerShell em um arquivo .psm1. O script e o diretório onde ele está armazenado devem usar o mesmo nome. Por exemplo, um script chamado MyPsScript.psm1 é armazenado em um diretório chamado MyPsScript.

O diretório do módulo precisa estar em um caminho especificado em $Env:PSModulePath. O diretório do módulo pode conter todos os recursos necessários para executar o script e um arquivo de manifesto do módulo que descreve ao PowerShell como o módulo funciona.

Criar um módulo básico do PowerShell

As etapas a seguir descrevem como criar um módulo do PowerShell.

  1. Salve um script do PowerShell com uma extensão de .psm1. Use o mesmo nome para o script e o diretório em que o script é salvo.

    Salvar um script com a extensão .psm1 significa que você pode usar os cmdlets do módulo, como Import-Module. Os cmdlets do módulo existem principalmente para que você possa importar e exportar seu código para os sistemas de outros usuários. A solução alternativa seria carregar seu código em outros sistemas e, em seguida, fazer o dot-source na memória ativa, o que não é uma solução escalonável. Para obter mais informações, consulte Noções básicas sobre um módulo do Windows PowerShell. Por padrão, quando os usuários importam seu arquivo .psm1, todas as funções em seu script são acessíveis, mas as variáveis não são.

    Um exemplo de script do PowerShell, intitulado Show-Calendar, está disponível no final deste artigo.

    function Show-Calendar {
param(
    [datetime] $Start = [datetime]::Today,
    [datetime] $End = $Start,
    $FirstDayOfWeek,
    [int[]] $HighlightDay,
    [string[]] $HighlightDate = [datetime]::Today.ToString('yyyy-MM-dd')
    )

    #actual code for the function goes here see the end of the topic for the complete code sample
}

  2. Para controlar o acesso do usuário a determinadas funções ou variáveis, chame Export-ModuleMember no final do script.

    O código de exemplo na parte inferior do artigo tem apenas uma função, que por padrão seria exposta. No entanto, é recomendável que você chame explicitamente quais funções deseja expor, conforme descrito no código a seguir:

    function Show-Calendar {
      }
Export-ModuleMember -Function Show-Calendar

    Você pode restringir o que é importado usando um manifesto de módulo. Para obter mais informações, consulte Importando um módulo do PowerShell e como gravar um manifesto do módulo do PowerShell.

  3. Se você tiver módulos que seu próprio módulo precisa carregar, poderá usar Import-Module, na parte superior do módulo.

    O cmdlet Import-Module importa um módulo direcionado para um sistema e pode ser usado posteriormente no procedimento para instalar seu próprio módulo. O código de exemplo na parte inferior deste artigo não usa nenhum módulo de importação. Mas, se isso acontecesse, eles seriam listados na parte superior do arquivo, conforme mostrado no seguinte código:

    Import-Module GenericModule

  4. Para descrever seu módulo para o sistema de Ajuda do PowerShell, você pode usar comentários de ajuda padrão dentro do arquivo ou criar um arquivo de Ajuda adicional.

    O exemplo de código na parte inferior deste artigo inclui as informações de ajuda nos comentários. Você também pode escrever arquivos XML expandidos que contêm conteúdo de ajuda adicional. Para obter mais informações, consulte Escrevendo a Ajuda para módulos do Windows PowerShell.

  5. Se você tiver módulos adicionais, arquivos XML ou outro conteúdo que deseja empacotar com seu módulo, poderá usar um manifesto do módulo.

    Um manifesto de módulo é um arquivo que contém os nomes de outros módulos, layouts de diretório, números de controle de versão, dados de autor e outras informações. O PowerShell usa o arquivo de manifesto do módulo para organizar e implantar sua solução. Para obter mais informações, consulte Como escrever um manifesto de módulo do PowerShell.

  6. Para instalar e executar o módulo, salve o módulo em um dos caminhos apropriados do PowerShell e use Import-Module.

    Os caminhos em que você pode instalar o módulo estão localizados na variável global $Env:PSModulePath. Por exemplo, um caminho comum para salvar um módulo em um sistema seria %SystemRoot%/users/<user>/Documents/PowerShell/Modules/<moduleName>. Certifique-se de criar um diretório para o módulo que usa o mesmo nome do módulo de script, mesmo que seja apenas um único arquivo .psm1. Se você não salvou o módulo em um desses caminhos, precisará especificar o local do módulo no comando Import-Module. Caso contrário, o PowerShell não poderá localizar o módulo.

    Observação

    A partir do PowerShell 3.0, se você colocou o módulo em um dos caminhos do módulo do PowerShell, não será necessário importá-lo explicitamente. Seu módulo é carregado automaticamente quando um usuário chama sua função. Para obter mais informações sobre o caminho do módulo, consulte Importando um módulo do PowerShell e about_PSModulePath.

  7. Para remover um módulo do serviço ativo na sessão atual do PowerShell, use Remove-Module.

    Observação

    Remove-Module remove um módulo da sessão atual do PowerShell, mas não desinstala o módulo nem exclui os arquivos do módulo.

Show-Calendar exemplo de código

O exemplo a seguir é um módulo de script que contém uma única função chamada Show-Calendar. Essa função exibe uma representação visual de um calendário. O exemplo contém as cadeias de caracteres de Ajuda do PowerShell para a sinopse, descrição, valores de parâmetro e código. Quando o módulo é importado, o comando Export-ModuleMember garante que a função Show-Calendar seja exportada como um membro do módulo.

<#
 .SYNOPSIS
  Displays a visual representation of a calendar.

 .DESCRIPTION
  Displays a visual representation of a calendar. This function supports multiple months
  and lets you highlight specific date ranges or days.

 .PARAMETER Start
  The first month to display.

 .PARAMETER End
  The last month to display.

 .PARAMETER FirstDayOfWeek
  The day of the month on which the week begins.

 .PARAMETER HighlightDay
  Specific days (numbered) to highlight. Used for date ranges like (25..31).
  Date ranges are specified by the Windows PowerShell range syntax. These dates are
  enclosed in square brackets.

 .PARAMETER HighlightDate
  Specific days (named) to highlight. These dates are surrounded by asterisks.

 .EXAMPLE
   # Show a default display of this month.
   Show-Calendar

 .EXAMPLE
   # Display a date range.
   Show-Calendar -Start "March, 2010" -End "May, 2010"

 .EXAMPLE
   # Highlight a range of days.
   Show-Calendar -HighlightDay (1..10 + 22) -HighlightDate "2008-12-25"
#>
function Show-Calendar {
param(
    [datetime] $Start = [datetime]::Today,
    [datetime] $End = $Start,
    $FirstDayOfWeek,
    [int[]] $HighlightDay,
    [string[]] $HighlightDate = [datetime]::Today.ToString('yyyy-MM-dd')
    )

## Determine the first day of the start and end months.
$Start = New-Object DateTime $Start.Year,$Start.Month,1
$End = New-Object DateTime $End.Year,$End.Month,1

## Convert the highlighted dates into real dates.
[datetime[]] $HighlightDate = [datetime[]] $HighlightDate

## Retrieve the DateTimeFormat information so that the
## calendar can be manipulated.
$dateTimeFormat  = (Get-Culture).DateTimeFormat
if($FirstDayOfWeek)
{
    $dateTimeFormat.FirstDayOfWeek = $FirstDayOfWeek
}

$currentDay = $Start

## Process the requested months.
while($Start -le $End)
{
    ## Return to an earlier point in the function if the first day of the month
    ## is in the middle of the week.
    while($currentDay.DayOfWeek -ne $dateTimeFormat.FirstDayOfWeek)
    {
        $currentDay = $currentDay.AddDays(-1)
    }

    ## Prepare to store information about this date range.
    $currentWeek = New-Object PsObject
    $dayNames = @()
    $weeks = @()

    ## Continue processing dates until the function reaches the end of the month.
    ## The function continues until the week is completed with
    ## days from the next month.
    while(($currentDay -lt $Start.AddMonths(1)) -or
        ($currentDay.DayOfWeek -ne $dateTimeFormat.FirstDayOfWeek))
    {
        ## Determine the day names to use to label the columns.
        $dayName = "{0:ddd}" -f $currentDay
        if($dayNames -notcontains $dayName)
        {
            $dayNames += $dayName
        }

        ## Pad the day number for display, highlighting if necessary.
        $displayDay = " {0,2} " -f $currentDay.Day

        ## Determine whether to highlight a specific date.
        if($HighlightDate)
        {
            $compareDate = New-Object DateTime $currentDay.Year,
                $currentDay.Month,$currentDay.Day
            if($HighlightDate -contains $compareDate)
            {
                $displayDay = "*" + ("{0,2}" -f $currentDay.Day) + "*"
            }
        }

        ## Otherwise, highlight as part of a date range.
        if($HighlightDay -and ($HighlightDay[0] -eq $currentDay.Day))
        {
            $displayDay = "[" + ("{0,2}" -f $currentDay.Day) + "]"
            $null,$HighlightDay = $HighlightDay
        }

        ## Add the day of the week and the day of the month as note properties.
        $currentWeek | Add-Member NoteProperty $dayName $displayDay

        ## Move to the next day of the month.
        $currentDay = $currentDay.AddDays(1)

        ## If the function reaches the next week, store the current week
        ## in the week list and continue.
        if($currentDay.DayOfWeek -eq $dateTimeFormat.FirstDayOfWeek)
        {
            $weeks += $currentWeek
            $currentWeek = New-Object PsObject
        }
    }

    ## Format the weeks as a table.
    $calendar = $weeks | Format-Table $dayNames -AutoSize | Out-String

    ## Add a centered header.
    $width = ($calendar.Split("`n") | Measure-Object -Maximum Length).Maximum
    $header = "{0:MMMM yyyy}" -f $Start
    $padding = " " * (($width - $header.Length) / 2)
    $displayCalendar = " `n" + $padding + $header + "`n " + $calendar
    $displayCalendar.TrimEnd()

    ## Move to the next month.
    $Start = $Start.AddMonths(1)

}
}
Export-ModuleMember -Function Show-Calendar
  • Last updated on