about_Member-Access_Enumeration

Artikel
2025-01-28

Kurze Beschreibung

Beschreibt die automatische Auflistung von Sammlungen bei Verwendung des Mitgliedszugriffs-Operators.

Lange Beschreibung

PowerShell verwaltet eine Liste von Typen, die aufgezählt werden können. Ab PowerShell 3.0 verbessert die Funktion member-access enumeration die Verwendung des Mitgliedszugriffs-Operators (.) für Sammlungsobjekte, die aufzählbar sind.

Mit der Memberzugriffsenumeration können Sie einfacheren und kürzeren Code schreiben. Anstatt ein Auflistungsobjekt an jedes Element in der Auflistung zu ForEach-Object verteilen oder die ForEach()systeminterne Methode zu verwenden, können Sie den Memberzugriffsoperator für das Auflistungsobjekt verwenden.

Die folgenden Beispiele führen zu denselben Ergebnissen. Das letzte Beispiel demonstriert die Verwendung des member-access-Operators:

PS> Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName }
Windows Event Log
COM+ Event System
PS> (Get-Service -Name event*).ForEach({ $_.DisplayName })
Windows Event Log
COM+ Event System
PS> (Get-Service -Name event*).DisplayName
Windows Event Log
COM+ Event System

Hinweis

Sie können den Memberzugriffsoperator verwenden, um die Werte einer Eigenschaft für Elemente in einer Auflistung abzurufen, aber Sie können ihn nicht verwenden, um sie direkt festzulegen. Weitere Informationen finden Sie unter about_Arrays. Die member-access-Auflistung ist eine praktische Funktion. Es kann feine Unterschiede im Verhalten und in der Leistung zwischen den verschiedenen Enumerationsmethoden geben.

Wenn Sie den Operator member-access auf ein Objekt anwenden und das angegebene Mitglied in diesem Objekt existiert, wird das Mitglied aufgerufen. Wenn Sie den Memberzugriffsoperator für ein Auflistungsobjekt verwenden, das nicht über das angegebene Mitglied verfügt, listet PowerShell die Elemente in dieser Auflistung auf und verwendet für jedes aufgezählte Element den Memberzugriffsoperator.

Während der Memberzugriffsenumeration für eine Eigenschaft gibt der Operator den Wert der Eigenschaft für jedes Element mit dieser Eigenschaft zurück. Wenn keine Elemente über die angegebene Eigenschaft verfügen, gibt der Operator zurück $null.

Während der Memberzugriffsenumeration für eine Methode versucht der Operator, die Methode für jedes Element in der Auflistung aufzurufen. Wenn ein Element in der Auflistung nicht über die angegebene Methode verfügt, gibt der Operator die MethodNotFound-Ausnahme zurück.

Warnung

Während der Memberzugriffsenumeration für eine Methode wird die Methode für jedes Element in der Auflistung aufgerufen. Wenn die methode, die Sie aufrufen, Änderungen vorgibt, werden die Änderungen für jedes Element in der Auflistung vorgenommen. Wenn während der Aufzählung ein Fehler auftritt, wird die Methode nur für die Elemente aufgerufen, die vor dem Fehler aufgezählt werden. Für zusätzliche Sicherheit sollten Sie das manuelle Aufzählen der Elemente und die explizite Behandlung von Fehlern in Betracht ziehen.

Zugriff auf Mitglieder eines nicht aufzählbaren Objekts

Wenn Sie den member-access-Operator auf ein Objekt verwenden, das keine aufzählbare Sammlung ist, ruft PowerShell das Mitglied auf, um den Wert der Eigenschaft oder die Ausgabe der Methode für dieses Objekt zurückzugeben.

PS> $MyString = 'abc'
PS> $MyString.Length
3
PS> $MyString.ToUpper()
ABC

Wenn Sie den member-access-Operator auf ein nicht aufzählbares Objekt anwenden, das nicht über das Mitglied verfügt, gibt PowerShell $null für die fehlende Eigenschaft oder einen MethodNotFound Fehler für die fehlende Methode zurück.

PS> $MyString = 'abc'
PS> $null -eq $MyString.DoesNotExist
True
PS> $MyString.DoesNotExist()
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

Zugriff auf Mitglieder eines Sammlungsobjekts

Wenn Sie den Memberzugriffsoperator für ein Auflistungsobjekt verwenden, das über das Element verfügt, wird immer der Eigenschaftswert oder das Methodenergebnis für das Auflistungsobjekt zurückgegeben.

Zugriff auf Mitglieder, die in der Sammlung, aber nicht in ihren Elementen vorhanden sind

In diesem Beispiel sind die angegebenen Elemente in der Auflistung vorhanden, aber nicht die darin aufgeführten Elemente.

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

Zugriff auf Mitglieder, die in der Sammlung und ihren Objekten vorhanden sind

In diesem Beispiel sind die angegebenen Elemente sowohl für die Auflistung als auch für die darin enthaltenen Elemente vorhanden. Vergleichen Sie die Ergebnisse der Befehle mithilfe des Memberzugriffsoperators in der Auflistung mit den Ergebnissen, indem Sie den Memberzugriffsoperator für die Auflistungselemente in ForEach-Object. In der Auflistung gibt der Operator den Eigenschaftswert oder das Methodenergebnis für das Auflistungsobjekt und nicht die darin enthaltenen Elemente zurück.

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

Hinweis

Sammlungen, die die System.Collections.IDictionary-Schnittstelle implementieren, z . B. HashTable und OrderedDictionary, weisen ein anderes Verhalten auf. Wenn Sie den Memberzugriffsoperator für ein Wörterbuch verwenden, das über einen Schlüssel mit demselben Namen wie eine Eigenschaft verfügt, wird der Wert des Schlüssels anstelle der Eigenschaft zurückgegeben.

Sie können mit dem systeminternen Element psbaseauf den Eigenschaftswert des Wörterbuchobjekts zugreifen. Wenn der Schlüsselname beispielsweise lautet keys und Sie die Sammlung der HashTable-Schlüssel zurückgeben möchten, verwenden Sie die folgende Syntax:

$hashtable.psbase.Keys

Zugriff auf Mitglieder, die in allen Elementen einer Sammlung vorhanden sind, aber nicht in der Sammlung selbst

Wenn Sie den member-access-Operator auf ein Sammlungsobjekt verwenden, das nicht über das Mitglied verfügt, die darin enthaltenen Elemente jedoch schon, listet PowerShell die Elemente in der Sammlung auf und gibt den Eigenschaftswert oder das Methodenergebnis für jedes Element zurück.

PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
PS> $Collection.Length
1
1
1
PS> $Collection.ToUpper()
A
B
C

Zugriff auf Mitglieder, die in der Sammlung oder ihren Elementen nicht vorhanden sind

Wenn Sie den member-access-Operator auf ein Sammlungsobjekt verwenden, das weder über das Mitglied noch über die Elemente in der Sammlung verfügt, gibt der Befehl $null zurück, wenn Sie eine Eigenschaft angeben, oder einen MethodNotFound-Fehler, wenn Sie eine Methode angeben.

PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
PS> $null -eq $Collection.DoesNotExist
True
PS> $Collection.DoesNotExist()
InvalidOperation: Method invocation failed because [System.String] does not
contain a method named 'DoesNotExist'.

Da das Sammlungsobjekt nicht über das Mitglied verfügt, hat PowerShell die Elemente in der Sammlung aufgelistet. Beachten Sie, dass der Fehler MethodNotFound angibt, dass System.String die Methode nicht enthält, im Gegensatz zu System.Collections.Generic.List.

Zugriffsmethoden, die nur für einige Elemente in einer Sammlung existieren

Wenn Sie den member-access-Operator verwenden, um auf eine Methode eines Auflistungsobjekts zuzugreifen, das nicht über die Methode verfügt und nur einige Elemente in der Sammlung über sie verfügen, gibt der Befehl einen MethodNotFound-Fehler für das erste Element in der Sammlung zurück, das nicht über die Methode verfügt. Obwohl die Methode für einige Elemente aufgerufen wird, gibt der Befehl nur den Fehler zurück.

PS> @('a', 1, 'c').ToUpper()
InvalidOperation: Method invocation failed because [System.Int32] does not
contain a method named 'ToUpper'.

Eigenschaften abrufen, die nur bei einigen Elementen in einer Auflistung vorhanden sind

Wenn Sie den member-access-Operator verwenden, um auf eine Eigenschaft eines Sammlungsobjekts zuzugreifen, das die Eigenschaft nicht hat und nur einige Elemente in der Sammlung sie haben, gibt der Befehl den Eigenschaftswert für jedes Element in der Sammlung zurück, das die Eigenschaft hat.

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

Zugriff auf Mitglieder einer eingebetteten Sammlung

Wenn eine aufzählbare Sammlung eine eingebettete Sammlung enthält, wird der Zugriff auf die Mitglieder auf jede eingebettete Sammlung angewendet.

Ein Beispiel: $a ist ein Array, das zwei Elemente enthält: ein eingebettetes Array von Zeichenfolgen und eine einzelne Zeichenfolge.

# Get the count of items in the array.
PS> $a.Count
2
# Get the count of items in each nested item.
PS> $a.GetEnumerator().Count
2
1
# Call the ToUpper() method on all items in the nested array.
PS> $a = @(, ('bar', 'baz'), 'foo')
PS> $a.ToUpper()
BAR
BAZ
FOO

Wenn Sie den member-access-Operator verwenden, listet PowerShell die Elemente in $a auf und ruft die Methode ToUpper() für alle Elemente auf.

Notizen

Wie bereits erwähnt, kann es subtile Verhaltens- und Leistungsunterschiede zwischen den verschiedenen Aufzählungsmethoden geben.

Fehler führen zu verlorenem Output

Wenn die member-access-Auflistung durch einen Fehler beendet wird, wird die Ausgabe von vorherigen erfolgreichen Methodenaufrufen nicht zurückgegeben. Zu den abschließenden Fehlerbedingungen gehören:

Das enumerierte Objekt verfügt nicht über die angeforderte Methode.
die Methode, auf die zugegriffen wird, löst einen Beendigungsfehler aus

Betrachten Sie das folgende Beispiel:

class Class1 { [Object] Foo() { return 'Bar' } }
class Class2 { [void] Foo() { throw 'Error' } }
class Class3 {}

$example1 = ([Class1]::new(), [Class1]::new())
$example2 = ([Class1]::new(), [Class2]::new())
$example3 = ([Class1]::new(), [Class3]::new())

Beide Elemente in $example1 haben die Methode Foo(), so dass der Methodenaufruf erfolgreich ist.

PS> $example1.Foo()
Bar
Bar

Die Methode Foo() für das zweite Element in $example2 löst einen Fehler aus, so dass die Auflistung fehlschlägt.

PS> $example2.Foo()
Exception:
Line |
   2 |  class Class2 { [void] Foo() { throw 'Error' } }
     |                                ~~~~~~~~~~~~~
     | Error

Das zweite Element in $example2 verfügt nicht über die Methode Foo(), so dass die Auflistung fehlschlägt.

PS> $example3.Foo()
InvalidOperation: Method invocation failed because [Class3] does not contain
a method named 'Foo'.

Vergleichen Sie dies mit der Auflistung mittels ForEach-Object

PS> $example2 | ForEach-Object -MemberName Foo
Bar
ForEach-Object: Exception calling "Foo" with "0" argument(s): "Error"
PS> $example3 | ForEach-Object -MemberName Foo
Bar

Beachten Sie, dass die Ausgabe den erfolgreichen Aufruf von Foo() für das erste Element im Array zeigt.

Sammlungen mit PSCustomObject-Instanzen

Wenn die Sammlung von Objekten Instanzen von PSCustomObject-Elementen enthält, gibt PowerShell unerwartet $null-Werte zurück, wenn die Eigenschaft, auf die zugegriffen wird, nicht vorhanden ist.

In den folgenden Beispielen verfügt mindestens ein Objekt über die referenzierte Eigenschaft.

PS> $foo = [pscustomobject]@{ Foo = 'Foo' }
PS> $bar = [pscustomobject]@{ Bar = 'Bar' }
PS> $baz = [pscustomobject]@{ Baz = 'Baz' }
PS> ConvertTo-Json ($foo, $bar, $baz).Foo
[
  "Foo",
  null,
  null
]
PS> ConvertTo-Json ((Get-Process -Id $PID), $foo).Name
[
  "pwsh",
  null
]

Sie würden erwarten, dass PowerShell ein einzelnes Objekt für das Element zurückgibt, das die angegebene Eigenschaft hat. Stattdessen gibt PowerShell auch einen $null Wert für jedes Element zurück, das die Eigenschaft nicht hat.

Weitere Informationen zu diesem Verhalten finden Sie unter PowerShell Issue #13752.

Freigeben über