about_Member-Access_Enumeration

Descrição breve

Descreve a enumeração automática de itens de coleção de lista ao usar o operador de acesso de membro.

Descrição longa

A partir do PowerShell 3.0, o recurso de enumeração de acesso de membro melhora a conveniência de usar o operador de acesso de membro (.) em objetos de coleção de listas. Quando você usa o operador de acesso de membro para acessar um membro que não existe em uma coleção, o PowerShell enumera automaticamente os itens na coleção e tenta acessar o membro especificado em cada item.

A enumeração de acesso de membro ajuda você a escrever um código mais simples e mais curto. Em vez de canalizar um objeto de coleção ou ForEach-Object usar o ForEach()método intrínseco para acessar membros em cada item da coleção, você pode usar o operador de acesso de membro no objeto de coleção.

Esses comandos são funcionalmente idênticos ao último que demonstra o uso do operador de acesso de membro:

Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName }
(Get-Service -Name event*).ForEach({ $_.DisplayName })
(Get-Service -Name event*).DisplayName

Windows Event Log
COM+ Event System

Windows Event Log
COM+ Event System

Windows Event Log
COM+ Event System

Quando você usa o operador de acesso de membro em qualquer objeto e o membro especificado existe nesse objeto, o membro é invocado. Para membros da propriedade, o operador retorna o valor dessa propriedade. Para membros do método, o operador chama esse método no objeto.

Quando você usa o operador de acesso de membro em um objeto de coleção de listas que não tem o membro especificado, o PowerShell enumera automaticamente os itens nessa coleção e usa o operador de acesso de membro em cada item enumerado.

Você pode verificar se um objeto é uma coleção de listas verificando se seu tipo implementa a interface IList :

$List = @('a', 'b')
$Hash = @{ a = 'b' }
$List.GetType().ImplementedInterfaces.Name -contains 'IList'
$Hash.GetType().ImplementedInterfaces.Name -contains 'IList'

True

False

Durante a enumeração de acesso de membro para uma propriedade, o operador retorna o valor da propriedade para cada item que tem essa propriedade. Se nenhum item tiver a propriedade especificada, o operador retornará $null.

Durante a enumeração de acesso de membro para um método, o operador tenta chamar o método em cada item da coleção. Se algum item na coleção não tiver o método especificado, o operador retornará a exceção MethodNotFound .

Os exemplos a seguir detalham o comportamento do operador de acesso de membro em todos os cenários possíveis.

Acessando membros de um objeto que não é de lista

Quando você usa o operador de acesso de membro em um objeto que não é uma coleção de listas e que tem o membro, o comando retorna o valor da propriedade ou saída do método para esse objeto.

$MyString = 'abc'
$MyString.Length
$MyString.ToUpper()

3

ABC

Quando você usa o operador de acesso de membro em um objeto que não é de lista que não tem o membro, o comando retorna $null se você especificar uma propriedade ou um erro MethodNotFound se você especificar um método.

$MyString = 'abc'
$null -eq $MyString.DoesNotExist
$MyString.DoesNotExist()

True

Method invocation failed because [System.String] does not contain a method
named 'DoesNotExist'.
At line:1 char:1
+ $MyString.DoesNotExist()
+ ~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (:) [], RuntimeException
    + FullyQualifiedErrorId : MethodNotFound

Acessando membros de um objeto de coleção de listas

Quando você usa o operador de acesso ao membro em um objeto de coleção que tem o membro, ele sempre retorna o valor da propriedade ou o resultado do método para o objeto de coleção.

Acessando membros que existem na coleção, mas não seus itens

Neste exemplo, os membros especificados existem na coleção, mas não os itens nela.

[System.Collections.Generic.List[string]]$Collection = @('a', 'b')
$Collection.IsReadOnly
$Collection.Add('c')
$Collection

False

a
b
c

Acessando membros que existem na coleção e seus itens

Para este exemplo, os membros especificados existem na coleção e nos itens nela. Compare os resultados dos comandos usando o operador de acesso de membro na coleção com os resultados do uso do operador de acesso de membro nos itens de coleção em ForEach-Object. Na coleção, o operador retorna o valor da propriedade ou o resultado do método para o objeto de coleção e não os itens nele.

[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
$Collection.Count
$Collection | ForEach-Object -Process { $_.Count }
$Collection.ToString()
$Collection | ForEach-Object -Process { $_.ToString() }

3

1
1
1

System.Collections.Generic.List`1[System.String]

a
b
c

$hashtable.PSBase.Keys

Acessando membros que existem em todos os itens de uma coleção, mas não em si mesmo

Quando você usa o operador de acesso de membro em um objeto de coleção que não tem o membro, mas os itens nele têm, o PowerShell enumera os itens na coleção e retorna o valor da propriedade ou o resultado do método para cada item.

[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
$Collection.Length
$Collection.ToUpper()

1
1
1

A
B
C

Acessando membros que não existem na coleção nem em seus itens

Quando você usa o operador de acesso de membro em um objeto de coleção que não tem o membro e nem os itens nele, o comando retorna $null se você especificar uma propriedade ou um MethodNotFound erro se você especificar um método.

[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
$null -eq $Collection.DoesNotExist
$Collection.DoesNotExist()

True

Method invocation failed because [System.String] does not contain a method
named 'DoesNotExist'.
At line:1 char:1
+ $Collection.DoesNotExist()
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (:) [], RuntimeException
    + FullyQualifiedErrorId : MethodNotFound

Como o objeto de coleção não tem o membro, o PowerShell enumerou os itens na coleção. Observe que o erro MethodNotFound especifica que System.String não contém o método em vez de System.Collections.Generic.List.

Acessando métodos que existem apenas em alguns itens em uma coleção

Quando você usa o operador de acesso de membro para acessar um método em um objeto de coleção que não tem o método e apenas alguns dos itens da coleção o têm, o comando retorna um MethodNotFound erro para o primeiro item da coleção que não tem o método. Mesmo que o método seja chamado em alguns itens, o comando retorna apenas o erro.

@('a', 1, 'c').ToUpper()

Method invocation failed because [System.Int32] does not contain a method
named 'ToUpper'.
At line:1 char:1
+ @('a', 1, 'c').ToUpper()
+ ~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (:) [], RuntimeException
    + FullyQualifiedErrorId : MethodNotFound

Acessando propriedades que existem apenas em alguns itens em uma coleção

Quando você usa o operador de acesso de membro para acessar uma propriedade em um objeto de coleção que não tem a propriedade e apenas alguns dos itens da coleção a têm, o comando retorna o valor da propriedade para cada item na coleção que tem a propriedade.

$CapitalizedProperty = @{
    MemberType = 'ScriptProperty'
    Name       = 'Capitalized'
    Value      = { $this.ToUpper() }
    PassThru   = $true
}
[System.Collections.Generic.List[object]]$MixedCollection = @(
    'a'
    ('b' | Add-Member @CapitalizedProperty)
    ('c' | Add-Member @CapitalizedProperty)
    'd'
)
$MixedCollection.Capitalized

B
C

Confira também

• about_Arrays
• about_Intrinsic_Members
• about_Methods
• about_Operators
• about_Properties