3. Conceitos básicos

Nota editorial

Importante

A Especificação da Linguagem Windows PowerShell 3.0 foi publicada em dezembro de 2012 e é baseada no Windows PowerShell 3.0. Essa especificação não reflete o estado atual do PowerShell. Não há nenhum plano para atualizar essa documentação para refletir o estado atual. Esta documentação é apresentada aqui para referência histórica.

O documento de especificação está disponível como um documento do Microsoft Word do Centro de Download da Microsoft em: https://www.microsoft.com/download/details.aspx?id=36389 esse documento do Word foi convertido para apresentação aqui no Microsoft Learn. Durante a conversão, algumas alterações editoriais foram feitas para acomodar a formatação para a plataforma Docs. Alguns erros de digitação e pequenos foram corrigidos.

3.1 Provedores e unidades

Um provedor de permite acesso a dados e componentes que, de outra forma, não seriam facilmente acessíveis na linha de comando. Os dados são apresentados em um formato consistente que se assemelha a uma unidade do sistema de arquivos.

Os dados expostos por um provedor são exibidos em uma unidade e os dados são acessados por meio de um caminho como acontece com uma unidade de disco. Os cmdlets internos de cada provedor gerenciam os dados na unidade do provedor.

O PowerShell inclui o seguinte conjunto de provedores internos para acessar os diferentes tipos de armazenamentos de dados:

Provedor	Nome da Unidade	Descrição	Ref.
Alias	Alias:	Aliases do PowerShell	§3.1.1
Ambiente	Env:	Variáveis de ambiente	§3.1.2
Sistema de Arquivos	A:, B:, C:, ...	Unidades de disco, diretórios e arquivos	§3.1.3
Função	Função:	Funções do PowerShell	§3.1.4
Variável	Variável:	Variáveis do PowerShell	§3.1.5

Windows PowerShell:

Provedor	Nome da Unidade	Descrição
Certificado	Certificado:	Certificados x509 para assinaturas digitais
Registro	HKLM: (HKEY_LOCAL_MACHINE), HKCU: (HKEY_CURRENT_USER)	Registro do Windows
WSMan	WSMan:	Informações de configuração do WS-Management

Os seguintes cmdlets lidam com provedores e unidades:

• Get-PSProvider: obtém informações sobre um ou mais provedores
• Get-PSDrive: obtém informações sobre uma ou mais unidades

O tipo de objeto que representa um provedor é descrito em §4.5.1. O tipo de um objeto que representa uma unidade está descrito na seção 4.5.2.

3.1.1 Apelidos

Um alias é um nome alternativo para um comando. Um comando pode ter vários aliases, e o nome original e todos os seus aliases podem ser usados de forma intercambiável. Um alias pode ser reatribuído. Um alias é um item (§3.3).

Um alias pode ser atribuído a outro alias; no entanto, o novo alias não é um alias do comando original.

O Alias do provedor é um namespace simples que contém apenas objetos que representam os aliases. As variáveis não possuem itens filho.

O PowerShell vem com um conjunto de aliases internos.

Os seguintes cmdlets tratam de aliases:

• New-Alias: cria um alias
• Set-Alias: cria ou altera um ou mais aliases
• Get-Alias: obtém informações sobre um ou mais apelidos
• Export-Alias: exporta um ou mais aliases para um arquivo

Quando um alias é criado para um comando usando New-Alias, parâmetros para esse comando não podem ser incluídos nesse alias. No entanto, a atribuição direta a uma variável no Alias: o namespace permite que os parâmetros sejam incluídos.

Nota

No entanto, é uma questão simples criar uma função que não faz nada mais do que conter a invocação desse comando com todos os parâmetros desejados e atribuir um alias a essa função.

O tipo de um objeto que representa um alias é descrito em §4.5.4.

Os objetos do alias são armazenados na unidade Alias: (seção 3.1).

3.1.2 Variáveis de ambiente

O provedor de ambiente do PowerShell permite que variáveis de ambiente do sistema operacional sejam recuperadas, adicionadas, alteradas, desmarcadas e excluídas.

O ambiente do provedor é um namespace simples que contém apenas objetos que representam as variáveis de ambiente. As variáveis não possuem itens filho.

O nome de uma variável de ambiente não pode incluir o sinal de igual (=).

As alterações nas variáveis de ambiente afetam somente a sessão atual.

Uma variável de ambiente é um item (§3.3).

O tipo de um objeto que representa uma variável de ambiente é descrito em §4.5.6.

Os objetos da variável de ambiente são armazenados na unidade Env: (seção 3.1).

3.1.3 Sistema de arquivos

O provedor do sistema de arquivos do PowerShell permite que diretórios e arquivos sejam criados, abertos, alterados e excluídos.

O provedor do sistema de arquivos é um namespace hierárquico que contém objetos que representam o sistema de arquivos subjacente.

Os arquivos são armazenados em unidades com nomes como A:, B:, C:e assim por diante (§3.1). Diretórios e arquivos são acessados usando notação de caminho (§3.4).

Um diretório ou arquivo é um item (§3.3).

3.1.4 Funções

O provedor de funções do PowerShell permite que funções (§8.10) e filtros (§8.10.1) sejam recuperadas, adicionadas, alteradas, desmarcadas e excluídas.

A Função do provedor é um namespace simples que contém apenas os objetos de função e filtro. Nem funções nem filtros possuem itens filhos.

As alterações nas funções afetam somente a sessão atual.

Uma função é um item (§3.3).

O tipo de um objeto que representa uma função é descrito em §4.5.10. O tipo de um objeto que representa um filtro é descrito em §4.5.11.

Os objetos de função são armazenados na unidade Function: (seção 3.1).

3.1.5 Variáveis

As variáveis podem ser definidas e manipuladas diretamente no idioma do PowerShell.

A variável de provedor é um namespace simples que contém apenas objetos que representam as variáveis. As variáveis não possuem itens filho.

Os seguintes cmdlets também lidam com variáveis:

• New-Variable: cria uma variável
• Set-Variable: cria ou altera as características de uma ou mais variáveis
• Get-Variable: obtém informações sobre uma ou mais variáveis
• Limpar-Variável: Exclui o valor de uma ou mais variáveis
• Remove-Variable: exclui uma ou mais variáveis

Como uma variável é um item (§3.3), ele pode ser manipulado pela maioria dos cmdlets relacionados a item.

O tipo de um objeto que representa uma variável é descrito em §4.5.3.

Os objetos de variáveis são armazenados na unidade Variable: (seção 3.1).

3.2 Locais de trabalho

O local de trabalho atual é o local padrão para o qual os comandos apontam. Esse é o local usado se um caminho explícito (§3.4) não for fornecido quando um comando é invocado. Esse local inclui a unidade atual.

Um host do PowerShell pode ter várias unidades, nesse caso, cada unidade tem sua própria localização atual.

Quando um nome de unidade é especificado sem um diretório, o local atual dessa unidade está implícito.

O local de trabalho atual pode ser salvo em uma pilha e, em seguida, definido como um novo local. Posteriormente, esse local salvo pode ser restaurado dessa pilha e se tornar o local de trabalho atual. Há dois tipos de pilhas de locais: a pilha de locais de trabalho padrão e zero ou mais pilhas de local de trabalho nomeadas definidas pelo usuário. Quando uma sessão é iniciada, a pilha de locais de trabalho padrão também é a pilha de locais de trabalho atual. No entanto, qualquer pilha de local de trabalho nomeada poderá se tornar a pilha de local de trabalho atual.

Os seguintes cmdlets lidam com locais:

• Set-Location: estabelece o local de trabalho atual
• Get-Location: determina o local de trabalho atual para as unidades especificadas ou os locais de trabalho para as pilhas especificadas
• Push-Location: salva o local de trabalho atual na parte superior de uma pilha de locais especificada
• Pop-Location: restaura o local de trabalho atual da parte superior de uma pilha de locais especificada

Os tipos de objeto que representam um local de trabalho e uma pilha de locais de trabalho são descritos em §4.5.5.

3.3 Itens

Um item é um alias (§3.1.1), uma variável (§3.1.5), uma função (§1 3.1.4), uma variável de ambiente (§3.1.2) ou um arquivo ou diretório em um sistema de arquivos (§3.1.3).

Os seguintes cmdlets lidam com itens:

• New-Item: Cria um Novo Item
• Set-Item: altera o valor de um ou mais itens
• Get-Item: obtém os itens no local especificado
• Get-ChildItem: obtém os itens e os itens filho no local especificado
• Copy-Item: copia um ou mais itens de um local para outro
• move-item: move um ou mais itens de um local para outro
• Renomear-item: renomeia um item
• invoke-item: executa a ação padrão em um ou mais itens
• Clear-Item: exclui o conteúdo de um ou mais itens, mas não exclui os itens (consulte
• remove-item: exclui os itens especificados

Os seguintes cmdlets lidam com o conteúdo dos itens:

• Get-Content: obtém o conteúdo do item
• Adicionar-Conteúdo: adiciona conteúdo aos itens especificados
• Set-Content: grava ou substitui o conteúdo de um item
• Clear-Content: exclui o conteúdo de um item

O tipo de objeto que representa um diretório é descrito em §4.5.17. O tipo de um objeto que representa um arquivo é descrito em §4.5.18.

3.4 Nomes de caminho

Todos os itens em um armazenamento de dados acessíveis por meio de um provedor do PowerShell podem ser identificados exclusivamente por seus nomes de caminho. Um nome de caminho é uma combinação do nome do item, do contêiner e dos subcontenentes nos quais o item está localizado e da unidade do PowerShell por meio da qual os contêineres são acessados.

Os nomes de caminho são divididos em um desses dois tipos: totalmente qualificado e relativo. Um nome de caminho totalmente qualificado consiste em todos os elementos que compõem um caminho. A sintaxe a seguir mostra os elementos em um nome de caminho totalmente qualificado:

Dica

A notação ~opt~ nas definições de sintaxe indica que a entidade lexical é opcional na sintaxe.

path:
    provider~opt~   drive~opt~   containers~opt~   item

provider:
    module~opt~   provider   ::

module:
    module-name   \

drive:
    drive-name   :

containers:
    container   \
    containers container   \

module-name refere-se ao módulo pai.

provedor se refere ao provedor do PowerShell por meio do qual se tem acesso ao armazenamento de dados.

drive refere-se ao drive do PowerShell suportado por um provedor específico do PowerShell.

Um contêiner pode conter outros contêineres, que podem conter outros contêineres e assim por diante, com o contêiner final segurando um item . Os contêineres devem ser especificados na ordem hierárquica na qual eles existem no armazenamento de dados.

Aqui está um exemplo de um nome de caminho:

E:\Accounting\InvoiceSystem\Production\MasterAccount\MasterFile.dat

Se o elemento final em um caminho contiver outros elementos, ele será um elemento de contêiner ; caso contrário, é um elemento folha .

Em alguns casos, um nome de caminho totalmente qualificado não é necessário; um nome de caminho relativo será suficiente. Um nome de caminho relativo é baseado no local de trabalho atual. O PowerShell permite que um item seja identificado com base em sua localização em relação ao local de trabalho atual. Um nome de caminho relativo envolve o uso de alguns caracteres especiais. A tabela a seguir descreve cada um desses caracteres e fornece exemplos de nomes de caminho relativos e nomes de caminho totalmente qualificados. Os exemplos na tabela baseiam-se no diretório de trabalho atual que está sendo definido como C:\Windows:

Símbolo	Descrição	caminho relativo	Caminho totalmente qualificado
.	Local de trabalho atual	.\System	C:\Windows\System
..	Pai do local de trabalho atual	..\Program Files	C:\Program Files
\	Raiz da unidade do local de trabalho atual	\Program Files	C:\Program Files
nenhum	Sem caracteres especiais	System	C:\Windows\System

Para usar um nome de caminho em um comando, insira esse nome como um nome de caminho totalmente qualificado ou relativo.

Os seguintes cmdlets lidam com caminhos:

• Convert-Path: converte um caminho do PowerShell em um caminho de provedor do PowerShell
• Join-Path: combina um caminho e um caminho filho em um único caminho
• Resolve-path: resolve os caracteres curinga em um caminho
• Split-Path: retorna a parte especificada de um caminho
• Test-Path: Determina se os elementos de um caminho existem ou se um caminho está bem formado

Alguns cmdlets (como Add-Content e Copy-Item usam filtros de arquivo. Um filtro de arquivo é um mecanismo para especificar os critérios para a seleção de um conjunto de caminhos.

O tipo de objeto que representa um caminho resolvido é descrito em §4.5.5. Os caminhos geralmente são manipulados como cadeias de caracteres.

3.5 Escopos

Introdução 3.5.1

Um nome pode indicar uma variável, uma função, um alias, uma variável de ambiente ou uma unidade. O mesmo nome pode indicar itens diferentes em locais diferentes em um script. Para cada item diferente que um nome indicar, esse nome será visível somente na região do texto do script chamada de escopo. Itens diferentes indicados pelo mesmo nome têm escopos diferentes ou estão em espaços de nome diferentes.

Os escopos podem aninhar, nesse caso, um escopo externo é chamado de escopo pai e os escopos aninhados são escopos filho desse pai. O escopo de um nome é o escopo no qual ele está definido e todos os escopos filho, a menos que ele seja privado. Em um escopo filho, um nome definido oculta os itens definidos com o mesmo nome nos escopos pai.

A menos que a notação dot source (seção 3.5.5) seja usada, cada um dos seguintes itens cria um novo escopo:

• Um arquivo de script
• Um bloco de script
• Uma função ou filtro

Considere o seguinte exemplo:

# Start of script
$x = 2; $y = 3
Get-Power $x $y

# Function defined in script
function Get-Power([int]$x, [int]$y) {
    if ($y -gt 0) {
        return $x * (Get-Power $x (--$y))
    } else {
        return 1
    }
}
# End of script

O escopo das variáveis $x e $y criados no script é o corpo desse script, incluindo a função definida dentro dele. A função Get-Power define dois parâmetros com esses mesmos nomes. Como cada função tem seu próprio escopo, essas variáveis são diferentes daquelas definidas no escopo pai e as ocultam do escopo pai. O escopo da função é aninhado dentro do escopo do script.

Observe que a função chama a si mesma recursivamente. Cada vez que ela faz isso, ela cria outro escopo aninhado, cada um com suas próprias variáveis $x e $y.

Veja um exemplo mais complexo, que também mostra escopos aninhados e reutilização de nomes:

# start of script scope
$x = 2              # top-level script-scope $x created
                    # $x is 2
F1                  # create nested scope with call to function F1
                    # $x is 2
F3                  # create nested scope with call to function F3
                    # $x is 2

function F1 {       # start of function scope
                    # $x is 2
    $x = $true      # function-scope $x created
                    # $x is $true

    & {             # create nested scope with script block
                    # $x is $true
        $x = 12.345 # scriptblock-scope $x created
                    # $x is 12.345
    }               # end of scriptblock scope, local $x goes away

                    # $x is $true
    F2              # create nested scope with call to function F2
                    # $x is $true
}                   # end of function scope, local $x goes away

function F2 {       # start of function scope
                    # $x is $true
    $x = "red"      # function-scope $x created
                    # $x is "red"
}                   # end of function scope, local $x goes away

function F3 {       # start of function scope
                    # $x is 2
    if ($x -gt 0) {
                    # $x is 2
        $x = "green"
                    # $x is "green"
    }               # end of block, but not end of any scope
                    # $x is still "green"
}                   # end of function scope, local $x goes away
# end of script scope

3.5.2 Números e nomes de escopo

O PowerShell dá suporte aos seguintes escopos:

• Global: esse é o escopo de nível mais alto. Todas as variáveis automáticas e de preferência são definidas nesse escopo. O escopo global é o escopo principal de todos os outros escopos e todos os outros escopos são subescopos do escopo global.

• Local: esse é o escopo atual em qualquer ponto de execução dentro de um script, bloco de script ou função. Qualquer escopo pode ser o escopo local.

• Script: Esse escopo existe para cada arquivo de script executado. O escopo do script é o escopo pai de todos os escopos criados a partir dele. Um bloco de script não tem seu próprio escopo de script; em vez disso, seu escopo de script é o do arquivo de script ancestral mais próximo. Embora não exista um escopo de módulo, o escopo do script fornece o equivalente.

Os nomes podem ser declarados como privados e, nesse caso, eles não ficam visíveis fora do escopo pai, nem mesmo para os escopos filho. O conceito de privado não é um escopo separado; é um alias para o escopo local com a adição de ocultar o nome, se usado como um local gravável.

Escopos podem ser referenciados por um número, que descreve a posição relativa de um escopo para outro. O escopo 0 indica o escopo local, o escopo 1 indica um escopo ancestral de 1 geração, o escopo 2 indica um escopo ancestral de 2 gerações e assim por diante. (Os números de escopo são usados por cmdlets que manipulam variáveis).

3.5.3 Escopo do nome da variável

Conforme mostrado pela produção a seguir, um nome de variável pode ser especificado com qualquer um dos seis escopos diferentes:

variable-scope:
    global:
    local:
    private:
    script:
    using:
    workflow:
    variable-namespace

O escopo é opcional. A tabela a seguir mostra o significado de cada um em todos os contextos possíveis. Ele também mostra o escopo quando nenhum escopo é especificado explicitamente:

Modificador de escopo	em um arquivo de script	dentro de um bloco de script	Em uma Função
global	Escopo global	Escopo global	Escopo global
roteiro	Escopo do arquivo de script ancestral mais próximo ou Global se não houver nenhum arquivo de script ancestral mais próximo	Escopo do arquivo de script ancestral mais próximo ou Global se não houver nenhum arquivo de script ancestral mais próximo	Escopo do arquivo de script ancestral mais próximo ou Global se não houver nenhum arquivo de script ancestral mais próximo
privado	Escopo Global/de Script/Local	Escopo local	Escopo local
local	Escopo Global/de Script/Local	Escopo local	Escopo local
using	Implementação definida	Implementação definida	Implementação definida
fluxo de trabalho	Implementação definida	Implementação definida	Implementação definida
nenhum	Escopo Global/de Script/Local	Escopo local	Escopo local

Informações de escopo variável também podem ser especificadas ao usar a família de cmdlets listados em (§3.1.5). Em particular, consulte o parâmetro Scopee os parâmetros Option Private e Option AllScope para obter mais informações.

O escopo using é usado para acessar variáveis definidas em outro escopo durante a execução de scripts por meio de cmdlets como Start-Job, Invoke-Command ou dentro de uma inlinescript-statement. Por exemplo:

$a = 42
Invoke-Command --ComputerName RemoteServer { $using:a } # returns 42
workflow foo
{
    $b = "Hello"
    inlinescript { $using:b }
}
foo # returns "Hello"

O fluxo de trabalho de escopo é usado com uma parallel-statement ou uma sequence-statement para acessar uma variável definida no fluxo de trabalho.

3.5.4 Escopo do nome da função

Um nome de função também pode ter um dos quatro escopos diferentes e a visibilidade desse nome é a mesma das variáveis (§3.5.3).

3.5.5 Notação dot source

Quando um arquivo de script, um bloco de script ou uma função é executada dentro de outro arquivo de script, bloco de script ou função, o arquivo de script executado cria um escopo aninhado. Por exemplo

Script1.ps1
& "Script1.ps1"
& { ... }
FunctionA

No entanto, quando a notação dot source é usada, não será criado nenhum escopo até que o comando seja executado; portanto, as adições/alterações feitas em seu próprio escopo local serão feitas no escopo atual. Por exemplo

. Script2.ps1
. "Script2.ps1"
. { ... }
. FunctionA

Módulos 3.5.6

Assim como um arquivo de script de nível superior fica na raiz de uma árvore hierárquica de escopo aninhado, o mesmo ocorre com cada módulo (seção 3.14). No entanto, por padrão, somente os nomes exportados por um módulo estão disponíveis pelo nome no contexto de importação. O parâmetro Global do cmdlet Import-Module permite que os nomes exportados tenham maior visibilidade.

3,6 Propriedades ReadOnly e Constant

Variáveis e aliases são descritos por objetos que contêm várias propriedades. Essas propriedades são definidas e manipuladas por duas famílias de cmdlets (§3.1.5, §3.1.1). Uma dessas propriedades é Options, que pode ser definida como ReadOnly ou Constant (usando o parâmetro Option). Uma variável ou alias marcada como ReadOnly pode ser removida e suas propriedades podem ser alteradas desde que o parâmetro Force seja especificado. No entanto, uma variável ou alias marcada como Constante não pode ser removida nem ter suas propriedades alteradas.

3.7 Sobrecargas de método e resolução de chamada

Introdução 3.7.1

Conforme indicado em §1, um procedimento externo disponibilizado pelo ambiente de execução (e escrito em algum idioma diferente do PowerShell) é chamado de método .

O nome de um método junto com o número e os tipos de seus parâmetros é chamado coletivamente de assinatura do método. (Observe que a assinatura não inclui o tipo de retorno do método.) O ambiente de execução pode permitir que um tipo tenha vários métodos com o mesmo nome, desde que cada um tenha uma assinatura diferente. Quando várias versões de algum método são definidas, esse método é considerado sobrecarregado. Por exemplo, o tipo Matemática (§4.3.8) contém um conjunto de métodos chamado Abs, que calcula o valor absoluto de um número especificado, em que o número especificado pode ter um de vários tipos. Os métodos nesse conjunto têm as seguintes assinaturas:

Abs(decimal)
Abs(float)
Abs(double)
Abs(int)
Abs(long)
Abs(SByte)
Abs(Int16)

Nesse caso, todos os métodos têm o mesmo número de argumentos; suas assinaturas diferem apenas por tipo de argumento.

Outro exemplo envolve o tipo Matriz (§4.3.2), que contém um conjunto de métodos chamado Copy que copia um intervalo de elementos de uma matriz para outra, começando no início de cada matriz (por padrão) ou em algum elemento designado. Os métodos nesse conjunto têm as seguintes assinaturas:

Copy(Array, Array, int)
Copy(Array, Array, long)
Copy(Array, int, Array, int, int)
Copy(Array, long, Array, long, long)

Nesse caso, as assinaturas diferem por tipo de argumento e, em alguns casos, por número de argumento também.

Na maioria das chamadas para métodos sobrecarregados, o número e o tipo dos argumentos passados correspondem exatamente a uma das sobrecargas e o método selecionado é óbvio. No entanto, se esse não for o caso, deverá haver uma forma de resolver qual versão sobrecarregada deverá ser chamada, se houver. Por exemplo

[Math]::Abs([byte]10) # no overload takes type byte
[Array]::Copy($source, 3, $dest, 5L, 4) # both int and long indexes

Outros exemplos incluem o tipo de cadeia de caracteres (isto é, System.String), que tem vários métodos sobrecarregados.

Embora o PowerShell tenha regras para resolver chamadas de método que não correspondem exatamente a uma assinatura sobrecarregada, o PowerShell não fornece uma maneira de definir métodos sobrecarregados.

Nota

Observação do editor: o PowerShell 5.0 adicionou a capacidade de definir classes baseadas em script. Essas classes podem conter métodos sobrecarregados.

3.7.2 Resolução de sobrecarga do método

Dada uma chamada de método (seção 7.1.3) com uma lista de expressões de argumento e um conjunto de métodos candidatos (ou seja, os métodos que poderiam ser chamados), o mecanismo para selecionar o melhor método é chamado de resolução de sobrecarga.

Considerando o conjunto de métodos candidatos aplicáveis (§3.7.3), o melhor método nesse conjunto é selecionado. Se o conjunto contiver apenas um método, esse método será o melhor método. Caso contrário, o melhor método é o método que é melhor do que todos os outros métodos em relação à lista de argumentos fornecida usando as regras mostradas em §3.7.4. Se não houver exatamente um método que seja melhor do que todos os outros métodos, a invocação do método será ambígua e um erro será relatado.

O melhor método deve ser acessível no contexto em que é chamado. Por exemplo, um script do PowerShell não pode chamar um método privado ou protegido.

O melhor método para uma chamada de um método estático deve ser um método estático, e o melhor método para uma chamada de um método de instância deve ser um método de instância.

3.7.3 Método aplicável

Diz-se que um método é aplicável em relação a uma lista de argumentos A quando um dos seguintes é verdadeiro:

• O número de argumentos em A é idêntico ao número de parâmetros que o método aceita.
• O método tem parâmetros M necessários e N parâmetros opcionais, e o número de argumentos em A é maior ou igual a M, mas menor que N.
• O método aceita um número variável de argumentos e o número de argumentos em A é maior do que o número de parâmetros que o método aceita.

Além de ter um número apropriado de argumentos, cada argumento em A deve corresponder ao modo de passagem de parâmetro do argumento e o tipo de argumento deve corresponder ao tipo de parâmetro ou deve haver uma conversão do tipo de argumento para o tipo de parâmetro.

Se o tipo de argumento for ref (§4.3.6), o parâmetro correspondente também deverá ser ref e o tipo de argumento para fins de conversão será o tipo do valor da propriedade do argumento ref.

Se o tipo de argumento for ref, o parâmetro correspondente poderá ser out em vez de ref.

Se o método aceita um número variável de argumentos, pode ser aplicável em forma normal ou forma expandida. Se o número de argumentos em A for idêntico ao número de parâmetros que o método aceita e o último parâmetro for uma matriz, o formulário dependerá da classificação de uma das duas conversões possíveis:

• A classificação da conversão do tipo do último argumento em A para o tipo de matriz do último parâmetro.
• A classificação da conversão do tipo do último argumento em A para o tipo de elemento do tipo de matriz do último parâmetro.

Se a primeira conversão (para o tipo de matriz) for melhor do que a segunda conversão (para o tipo de elemento da matriz), o método será aplicável na forma normal, caso contrário, ele será aplicável na forma expandida.

Se houver mais argumentos do que parâmetros, o método poderá ser aplicável somente em formulário expandido. Para ser aplicável no formato expandido, o último parâmetro deve ter o tipo de matriz. O método é substituído por um método equivalente que tem o último parâmetro substituído por parâmetros suficientes para considerar cada argumento incompatível em A. Cada tipo de parâmetro adicional é o tipo de elemento do tipo de matriz para o último parâmetro no método original. As regras acima para um método aplicável são aplicadas a este novo método e à lista de argumentos A.

3.7.4 Melhor método

Dada uma lista de argumentos A com um conjunto de expressões de argumento { E~1~, E~2~, ..., E~N~ } e dois métodos de aplicativo M~P~ e M~Q~ com tipos de parâmetro { P~1~, P~2~, ..., P~N~ } e { Q~1~, Q~2~, ..., Q~N~ }, M~P~ é definido como um método melhor do que M~Q~ se a classificação cumulativa de conversões para M~P~ é melhor do que para M~Q~.

A classificação cumulativa de conversões é calculada da seguinte maneira. Cada conversão vale um valor diferente dependendo do número de parâmetros, com a conversão de E~1~ valor N, E~2~ valor N-1, até E~N~ no valor de 1. Se a conversão de E~X~ para P~X~ for melhor do que a de E~X~ para Q~X~, o M~P~ acumulará N-X+1; caso contrário, M~Q~ acumula N-X+1. Se M~P~ e M~Q~ tiverem o mesmo valor, as seguintes regras de quebra de empate serão usadas, aplicadas na ordem:

• A classificação cumulativa de conversões entre tipos de parâmetro (ignorando tipos de argumento) é computada de maneira semelhante à classificação anterior, portanto, P~1~ é comparado com Q~1~, P~2~ em relação a Q~2~, ...e P~N~ em relação a Q~N~. A comparação será ignorada se o argumento tiver sido $nullou se os tipos de parâmetro não forem tipos numéricos. A comparação também será ignorada se a conversão de argumento E~X~ perder informações quando convertida em P~X~ mas não perder informações quando convertida em Q~X~ou vice-versa. Se os tipos de conversão de parâmetros forem comparados, se a conversão de P~X~ para Q~X~ for melhor do que a de Q~X~ para P~X~, o M~P~ acumulará N-X+1; caso contrário, M~Q~ acumula N-X+1. Essa regra de quebra de vínculo destina-se a preferir o método mais específico (ou seja, o método com parâmetros com os menores tipos de dados) se nenhuma informação for perdida em conversões ou preferir o método mais geral (ou seja, o método com os parâmetros com os maiores tipos de dados) se as conversões resultarem em perda de informações.
• Se ambos os métodos usarem seu formulário expandido, o método com mais parâmetros será o melhor método.
• Se um método usa o formulário expandido e o outro usa o formulário normal, o método que usa o formulário normal é o melhor método.

3.7.5 Conversão melhor

O texto a seguir marcado como este é específico do Windows PowerShell.

As conversões são classificadas da seguinte maneira, da mais baixa para a mais alta:

• T~1~[] para T~2~[] em que não há nenhuma conversão atribuível entre T~1~ e T~2~
• T para cadeia de caracteres em que T é qualquer tipo
• T~1~ para T~2~ onde T~1~ ou T~2~ define uma conversão personalizada de forma definida pela implementação
• T~1~ para T~2~ em que T~1~ implementa o IConvertible
• T~1~ para T~2~ em que T~1~ ou T~2~ implementa o método T~2~ op_Implicit(T1)
• T~1~ para T~2~ em que T~1~ ou T~2~ implementa o método T~2~ op_Explicit(T1)
• T~1~ para T~2~ em que T~2~ implementa um construtor usando um único argumento do tipo T~1~
• Uma das seguintes conversões:
  • string para T em que T define um método estático T Parse(string) ou T Parse(string, IFormatProvider)
  • T~1~ para T~2~ em que T~2~ é qualquer enumeração e T~1~ é uma cadeia de caracteres ou uma coleção de objetos que podem ser convertidos em cadeia de caracteres
• T para PSObject, onde T é qualquer tipo
• Qualquer uma das seguintes conversões: Language
  • T para bool onde T pode ser qualquer tipo numérico
  • string para T em que T é regex, wmisearcher, wmi, wmiclass, adsi, adsisearcherou type
  • de T a bool
  • T~1~ para Nullable[T~2~] em que existe uma conversão de T~1~ para T~2~
  • T para void
  • T~1~[] para T~2~[] em que existe uma conversão atribuível entre T~1~ e T~2~
  • T~1~ para T~2~[] onde T~1~ é uma coleção
  • IDictionary a Hashtable
  • T a ref
  • T a xml
  • scriptblock a delegate
  • T~1~ para T~2~ em que T~1~ é um tipo inteiro e T~2~ é uma enumeração
• $null para T em que T é qualquer tipo de valor
• $null até T em que T é qualquer tipo de referência
• Qualquer uma das seguintes conversões:

  • byte para T em que T é SByte

  • UInt16 para T onde T é SByte, byte ou Int16

  • Int16 para T onde T é SByte ou byte

  • UInt32 a T onde T está SByte, byte, Int16, UInt16ou int

  • int a T onde T está SByte, byte, Int16ou UInt16

  • de UInt64 para T com T sendo SByte, byte, Int16, UInt16, int, UInt32ou long

  • long para T onde T é SByte, byte, Int16, UInt16, int ou UInt32

  • float para T em que T é qualquer tipo inteiro ou decimal

  • double para T em que T é qualquer tipo inteiro ou decimal

  • decimal para T em que T é qualquer tipo de número inteiro

• Qualquer uma das seguintes conversões:
  • SByte para T em que T é byte, uint6, UInt32 ou UInt64
  • Int16 para T em que T é UInt16, UInt32ou UInt64
  • int para T onde T é UInt32 ou UInt64
  • long a UInt64
  • decimal a T onde T é float ou double
• Qualquer uma das seguintes conversões:
  • T para string em que T é qualquer tipo numérico
  • T para char em que T é qualquer tipo numérico
  • string para T em que T é qualquer tipo numérico
• Qualquer uma das seguintes conversões, essas conversões são consideradas conversões atribuíveis:
  • byte para T onde T é Int16, UInt16, int, UInt32, long, UInt64, single, double ou decimal
  • SByte para T onde T é Int16, UInt16, int, UInt32, long, UInt64, single, double ou decimal
  • UInt16 para T em que T seja int, UInt32, longou UInt64, single, doubleou decimal
  • Int16 para T em que T é int, UInt32, long ou UInt64, single, double ou decimal
  • UInt32 para T em que T é long ou UInt64, single, double ou decimal
  • int para T onde T é long, UInt64, single, double ou decimal
  • single para double
• T~1~ para T~2~ em que T~2~ é uma classe base ou interface de T~1~. Essa conversão é considerada uma conversão atribuível.
• string a char[]
• T para T – essa conversão é considerada uma conversão atribuível.

Para cada conversão do formulário T~1~ para T~2~[] em que T~1~ não é uma matriz e nenhuma outra conversão se aplica, se houver uma conversão de T~1~ para T~2~, a classificação da conversão é pior do que a conversão de T~1~ para T~2~, mas melhor do que qualquer conversão classificada menos do que a conversão de T~1~ para T~2~

3.8 Pesquisa de nome

É possível ter comandos de tipos diferentes todos com o mesmo nome. A ordem na qual a pesquisa de nome é executada nesse caso é alias, função, cmdlet e comando externo.

3.9 Pesquisa de nome de tipo

A seção 7.1.10 contém a seguinte afirmação: "Um type-literal é representado em uma implementação por algum tipo subjacente não especificado. Como resultado, um nome de tipo é um sinônimo para seu tipo subjacente." Exemplos de tipos são int, double, long[]e Hashtable.

Os nomes de tipo são correspondidos da seguinte forma: compare um determinado nome de tipo com a lista de aceleradores de tipo integrada, como int, long e double. Se uma correspondência for encontrada, esse será o tipo. Caso contrário, considere que o nome do tipo está totalmente qualificado e verifique se esse tipo existe no sistema host. Se uma correspondência for encontrada, esse será o tipo. Caso contrário, adicione o prefixo de namespace System.. Se uma correspondência for encontrada, esse será o tipo. Caso contrário, o nome do tipo está no erro. Esse algoritmo é aplicado a cada argumento de tipo para tipos genéricos. No entanto, não é necessário especificar a aridade (o número de argumentos ou operandos tomados por uma função ou operador).

3.10 Gerenciamento automático de memória

Vários operadores e cmdlets resultam na alocação de memória para objetos do tipo referência, como strings e matrizes. A alocação e a liberação dessa memória são gerenciadas pelo sistema de runtime do PowerShell. Ou seja, o PowerShell oferece coleta de lixo automática.

3.11 Ordem de execução

Um efeito colateral é uma alteração no estado do ambiente de execução de um comando. Uma alteração no valor de uma variável (por meio dos operadores de atribuição ou dos operadores pré e pós-incremento e decremento) é um efeito colateral, assim como uma alteração no conteúdo de um arquivo.

A menos que especificado de outra forma, as instruções são executadas em ordem lexical.

Exceto conforme especificado para alguns operadores, a ordem de avaliação de termos em uma expressão e a ordem em que ocorrem efeitos colaterais não são especificados.

Uma expressão que invoca um comando envolve a expressão que designa o comando e zero ou mais expressões que designam os argumentos cujos valores devem ser passados para esse comando. A ordem na qual essas expressões são avaliadas em relação umas às outras não é especificada.

3.12 Tratamento de erros

Quando um comando falha, isso é considerado um erro e as informações sobre esse erro são registradas em um registro de erro , cujo tipo não é especificado (§4.5.15); no entanto, esse tipo dá suporte à subscrição.

Um erro se enquadra em uma das duas categorias. Isso encerra a operação (um erro terminal ) ou não (um erro não-terminal ). Com um erro de encerramento, o erro é registrado e a operação é interrompida. Com um erro não fatal, o erro é registrado e a operação continua.

Erros que não causam encerramento são gravados no fluxo de erros. Embora essas informações possam ser redirecionadas para um arquivo, os objetos de erro são convertidos primeiro em cadeias de caracteres e informações importantes nesses objetos não seriam capturadas dificultando o diagnóstico se não fosse impossível. Em vez disso, o texto de erro pode ser redirecionado (§7,12) e o objeto de erro salvo em uma variável, como em $Error1 = command 2>&1.

A variável automática $Error contém uma coleção de registros de erro que representam erros recentes e o erro mais recente está em $Error[0]. Essa coleção é mantida em um buffer de modo que registros antigos sejam descartados à medida que novos são adicionados. A variável automática $MaximumErrorCount controla o número de registros que podem ser armazenados.

$Error contém todos os erros de todos os comandos misturados em uma coleção. Para coletar os erros de um comando específico, use o parâmetro comum ErrorVariable, que permite que uma variável definida pelo usuário seja especificada para manter a coleção.

3.13 Pipelines

Um pipeline é uma série de um ou mais comandos separados pelo operador de pipe | (U+007C). Cada comando recebe a entrada de seu antecessor e grava a saída em seu sucessor. A menos que a saída no final do pipeline seja descartada ou redirecionada para um arquivo, ela será enviada para o ambiente de host, que pode optar por gravá-la na saída padrão. Os comandos de um pipeline também podem receber entradas de argumentos. Por exemplo, considere o seguinte uso de comandos Get-ChildItem, Sort-Objecte Process-File, que criam uma lista de nomes de arquivo em um determinado diretório do sistema de arquivos, classificam um conjunto de registros de texto e executam algum processamento em um registro de texto, respectivamente:

Get-ChildItem
Get-ChildItem e:*.txt | Sort-Object -CaseSensitive | Process-File >results.txt

No primeiro caso, Get-ChildItem cria uma coleção de nomes dos arquivos no diretório atual/padrão. Essa coleção é enviada para o ambiente do host, que, por padrão, grava o valor de cada elemento na saída padrão.

No segundo caso, Get-ChildItem cria uma coleção de nomes dos arquivos no diretório especificado, usando o argumento e:*.txt. Essa coleção é escrita no comando Sort-Object, que, por padrão, classifica-os em ordem crescente, com diferenciação de maiúsculas e minúsculas (em virtude do argumento CaseSensitive). Em seguida, a coleção resultante é gravada no comando Process-File, que executa algum processamento (desconhecido). A saída desse comando é redirecionada para o arquivo results.txt.

Se um comando grava um único objeto, seu sucessor recebe esse objeto e, em seguida, termina depois de gravar seus próprios objetos no sucessor. Se, no entanto, um comando gravar vários objetos, eles serão entregues um de cada vez ao comando sucessor, que é executado uma vez por objeto. Esse comportamento é chamado fluxo. No processamento de fluxo, os objetos são gravados ao longo do pipeline assim que ficam disponíveis e não quando toda a coleção é produzida.

Ao processar uma coleção, um comando pode ser escrito de modo que ele possa fazer um processamento especial antes do elemento inicial e depois do elemento final.

3.14 Módulos

Um módulo é uma unidade reutilizável autônoma que permite que o código PowerShell seja particionado, organizado e abstraído. Um módulo pode conter comandos (como cmdlets e funções) e itens (como variáveis e aliases) que podem ser usados como uma única unidade.

Depois que um módulo for criado, ele deverá ser importado para uma sessão antes que os comandos e itens dentro dele possam ser usados. Depois de importados, comandos e itens se comportam como se fossem definidos localmente. Um módulo é importado explicitamente com o comando Import-Module. Um módulo também pode ser importado automaticamente conforme determinado de maneira definida pela implementação.

O tipo de um objeto que representa um módulo é descrito em §4.5.12.

Os módulos são discutidos detalhadamente em §11.

3.15 Expressões curinga

Uma expressão curinga pode conter zero ou mais dos seguintes elementos:

Elemento	Descrição
Caractere diferente de *, ?, ou [	Corresponde a esse caractere
*	Corresponde a zero ou mais caracteres. Para corresponder a um caractere * , use [*].
?	Faz a correspondência de qualquer caractere. Para fazer correspondência a um caractere ?, use [?].
[set]	Corresponde a qualquer caractere do conjunto , que não pode estar vazio. Se conjunto começar com ], esse colchete direito será considerado parte do conjunto de e o próximo colchete direito encerrará o conjunto; caso contrário, o primeiro colchete direito encerrará o conjunto. Se o conjunto começar ou terminar com -, o hífen-menos será considerado parte do conjunto ; caso contrário, indica um intervalo de pontos de código Unicode consecutivos, com os caracteres em ambos os lados do hífen-menos atuando como delimitadores inclusivos do intervalo. Por exemplo, A-Z indica as 26 letras maiúsculas em inglês e 0-9 indica os 10 dígitos decimais.

Nota

Mais informações podem ser encontradas em The Open Group Base Specifications: Pattern Matching", IEEE Std 1003.1, 2004 Edition.. No entanto, no PowerShell, o caractere de escape é um acento grave, não uma barra invertida.

3.16 Expressões regulares

Uma expressão regular pode conter zero ou mais dos seguintes elementos:

Elemento	Descrição
Caractere diferente de ., [, ^, *, $ou \	Corresponde a esse caractere
.	Faz a correspondência de qualquer caractere. Para corresponder a um caractere caractere, use \..
[set] [^set]	A forma [set] corresponde a qualquer caractere do set. A forma [^set] não corresponde a nenhum caractere do set. conjunto não pode estar vazio. Se conjunto começar com ] ou ^], esse colchete direito será considerado parte do conjunto e o próximo colchete direito encerrará o conjunto; caso contrário, o primeiro colchete direito encerrará o conjunto. Se o conjunto começar com - ou ^-, ou terminar com -, esse hífen é considerado parte do conjunto ; caso contrário, indica um intervalo de pontos de código Unicode consecutivos, com os caracteres em ambos os lados do hífen atuando como delimitadores desse intervalo inclusivo. Por exemplo, A-Z indica as 26 letras maiúsculas em inglês e 0-9 indica os 10 dígitos decimais.
*	Corresponde a zero ou mais ocorrências do elemento anterior.
+	Corresponde a uma das mais ocorrências do elemento anterior.
?	Corresponde a zero de uma das ocorrências do elemento anterior.
^	Corresponde ao início da cadeia de caracteres. Para fazer correspondência a um caractere ^, use \^.
$	Corresponde ao final da cadeia de caracteres. Para corresponder a um caractere $, use $.
\c	Escapa o caractere c, portanto, não é reconhecido como um elemento de expressão regular.

Nota

Mais informações podem ser encontradas em The Open Group Base Specifications: Regular Expressions, IEEE Std 1003.1, 2004 Edition..

Windows PowerShell: Há suporte para classes de caracteres disponíveis em expressões regulares do Microsoft .NET Framework, da seguinte maneira:

Elemento	Descrição
\p{name}	Corresponde a qualquer caractere na classe nomeada de caracteres especificada por nome. Os nomes com suporte são grupos Unicode e intervalos de blocos, como Ll, Nd, Z, IsGreek e IsBoxDrawing.
\P{name}	Faz a correspondência de texto não incluído nos grupos e nos intervalos de blocos especificados em name.
\w	Corresponde a qualquer caractere de palavra. Equivalente às categorias de caractere Unicode [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. Se o comportamento em conformidade com ECMAScript for especificado com a opção ECMAScript, \w será equivalente a [a-zA-Z_0-9].
\W	Corresponde a qualquer caractere sem palavra. Equivalente às categorias Unicode [\^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}].
\s	Corresponde a qualquer caractere de espaço em branco. Equivalente às categorias de caractere Unicode [\f\n\r\t\v\x85\p{Z}].
\S	Corresponde a qualquercaractere sem espaço em branco. Equivalente às categorias de caractere Unicode [\^\f\n\r\t\v\x85\p{Z}].
\d	Corresponde a qualquer dígito decimal. Equivalente a \p{Nd} para Unicode e [0-9] para comportamento não Unicode.
\D	Corresponde a qualquer caractere que não seja um dígito. Equivalente a \P{Nd} para Unicode e [\^0-9] para comportamento não Unicode.

Há suporte para quantificadores disponíveis em expressões regulares do Microsoft .NET Framework da seguinte maneira:

Elemento	Descrição
*	Especifica zero ou mais correspondências; por exemplo, \w* ou (abc)*. equivalente a {0,}.
+	Faz a correspondência de instâncias repetidas dos caracteres anteriores.
?	Especifica zero ou uma correspondência; por exemplo, \w? ou (abc)?. Equivalente a {0,1}.
{n}	Especifica exatamente n correspondências; por exemplo, (pizza){2}.
{n,}	Especifica pelo menos n correspondências; por exemplo, (abc){2,}.
{n,m}	Especifica pelo menos n, mas não mais que m correspondências.