about_Member-Access_Enumeration

Kurzbeschreibung

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.

Der Aufzählungsmitglied-Zugriff hilft Ihnen, einfacheren und kürzeren Code zu schreiben. Anstatt ein Sammlungsobjekt nach ForEach-Object zu pipen oder die ForEach()intrinsische Methode zu verwenden, um auf die Mitglieder jedes Elements in der Sammlung zuzugreifen, können Sie den Operator member-access auf das Sammlungsobjekt anwenden.

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 Mitgliedszugriffsoperator verwenden, um die Werte einer Eigenschaft für Elemente in einer Sammlung abzurufen, aber Sie können sie nicht direkt festlegen. Weitere Informationen finden Sie unter about_Arrays. Die member-access-Auflistung ist eine praktische Funktion. Zwischen den verschiedenen Aufzählungsmethoden kann es subtile Unterschiede im Verhalten und in der Leistung geben.

Wenn Sie den Mitgliedszugriffsoperator auf ein Objekt anwenden und das angegebene Mitglied auf 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 des Mitgliedszugriffs auf eine Eigenschaft gibt der Operator den Wert der Eigenschaft für jedes Element zurück, das diese Eigenschaft besitzt. Wenn keine Elemente über die angegebene Eigenschaft verfügen, gibt der Operator $nullzurück.

Während der Mitgliedszugriffsauflistung 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

Bei der Auflistung des Mitgliedszugriffs für eine Methode wird die Methode für jedes Element der Sammlung 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.

Access-Elemente 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 Memberzugriffsoperator bei einem nicht-aufzählbaren Objekt verwenden, das den Member nicht besitzt, gibt PowerShell $null für die fehlende Eigenschaft zurück oder einen MethodNotFound Fehler für die fehlende Methode.

PS> $MyString = 'abc'
PS> $null -eq $MyString.DoesNotExist
True
PS> $MyString.DoesNotExist()
InvalidOperation: Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.

Access-Elemente eines Auflistungsobjekts

Wenn Sie den Operator für den Mitgliedszugriff auf ein Sammlungsobjekt verwenden, das das Mitglied hat, gibt er immer den Eigenschaftswert oder das Ergebnis der Methode für das Sammlungsobjekt zurück.

Zugriffsmitglieder, die in der Sammlung vorhanden sind, jedoch nicht zu deren Elementen gehören

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

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 Mitglieder sowohl in der Sammlung als auch in den darin enthaltenen Objekten vorhanden. Vergleichen Sie die Ergebnisse der Befehle, die den Mitgliedszugriffsoperator auf die Sammlung verwenden, mit den Ergebnissen der Verwendung des Mitgliedszugriffsoperators auf die Sammlungselemente 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 Mitgliedszugriffsoperator auf ein Wörterbuch anwenden, dessen Schlüssel den gleichen Namen wie eine Eigenschaft hat, gibt er den Wert des Schlüssels anstelle der Eigenschaft zurück.

Sie können auf den Eigenschaftswert des Wörterbuchobjekts mit dem psbaseintrinsic Mitglied zugreifen. Wenn der Schlüsselname beispielsweise keys ist 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 Auflistungsobjekt nicht über das Mitglied verfügt, hat PowerShell die Elemente in der Auflistung enumeriert. 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 Memberzugriffsoperator verwenden, um auf eine Methode für ein Auflistungsobjekt zuzugreifen, das nicht über diese Methode verfügt und nur einige Elemente in der Auflistung diese Methode haben, gibt der Befehl einen MethodNotFound-Fehler für das erste Element in der Auflistung zurück, das die Methode nicht hat. 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'.

Zugriff auf Eigenschaften, die nur bei manchen Elementen in einer Sammlung 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 geschachtelten Sammlung

Wenn eine aufzählbare Auflistung eine geschachtelte Auflistung enthält, wird die Elementzugriffsaufzählung auf jede geschachtelte Auflistung angewendet.

Beispielsweise ist $a ein Array mit zwei Elementen: ein geschachteltes 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.

Hinweise

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 folgenden 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 Aufzählung unter Verwendung von 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 in der Ausgabe der erfolgreiche Aufruf von Foo() für das erste Element im Array angezeigt wird.

Sammlungen mit PSCustomObject-Instanzen

Wenn die Auflistung von Objekten Instanzen von PSCustomObject--Elementen enthält, gibt PowerShell unerwartet $null Werte zurück, wenn die aufgerufene Eigenschaft fehlt.

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.

Siehe auch

  • Zuletzt aktualisiert um