about_Member-Access_Enumeration

Artigo
10/04/2023

Breve descrição

Descreve a enumeração automática de itens de coleção de lista ao usar o operador member-access.

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 lista. 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 código mais simples e mais curto. Em vez de canalizar um objeto de coleção para ForEach-Object ou usar o ForEach()método intrínseco para acessar membros em cada item da coleção, você pode usar o operador member-access no objeto de coleção.

Estes 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

Nota

Você pode usar o operador de acesso de membro para obter os valores de uma propriedade em itens de uma coleção, mas não pode usá-lo para defini-los diretamente. Para obter mais informações, consulte about_Arrays.

Quando você usa o operador member-access 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 lista 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 lista vendo 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 qualquer item na coleção não tiver o método especificado, o operador retornará a exceção MethodNotFound .

Aviso

Durante a enumeração de acesso de membro para um método, o método é chamado em cada item da coleção. Se o método que você está chamando fizer alterações, as alterações serão feitas para cada item da coleção. Se ocorrer um erro durante a enumeração, o método é chamado somente nos itens enumerados antes do erro. Para maior segurança, considere enumerar manualmente os itens e manipular explicitamente quaisquer erros.

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 não listado

Quando você usa o operador member-access em um objeto que não é uma coleção de lista 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 member-access em um objeto non-list 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

InvalidOperation:
Line |
   3 |  $MyString.DoesNotExist()
     |  ~~~~~~~~~~~~~~~~~~~~~~~~
     | Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.

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

Quando você usa o operador member-access 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

Neste exemplo, os membros especificados existem na coleção e nos itens nela. Compare os resultados dos comandos usando o operador member-access na coleção com os resultados do uso do member-access operator nos itens de coleção no 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

Nota

As coleções que implementam a interface System.Collections.IDictionary , como HashTable e OrderedDictionary, têm um comportamento diferente. Quando você usa o operador de acesso de membro em um dicionário que tem uma chave com o mesmo nome de uma propriedade, ele retorna o valor da chave em vez do da propriedade.

Você pode acessar o valor da propriedade do objeto de dicionário com o membro intrínseco psbase. Por exemplo, se o nome da chave for keys e você quiser retornar a coleção das chaves HashTable , use esta sintaxe:

$hashtable.PSBase.Keys

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

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 nem na coleção nem em seus itens

Quando você usa o operador member-access 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 especificar um método.

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

True

InvalidOperation:
Line |
   3 |  $Collection.DoesNotExist()
     |  ~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.

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 de uma coleção

Quando você usa o operador member-access para acessar um método em um objeto de coleção que não tem o método e apenas alguns dos itens na 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()

InvalidOperation: Method invocation failed because [System.Int32] does not contain a method named 'ToUpper'.

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

Quando você usa o operador member-access para acessar uma propriedade em um objeto de coleção que não tem a propriedade e apenas alguns dos itens na 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