Condividi tramite


Add-Member

Aggiunge proprietà e metodi personalizzati a un'istanza di un oggetto PowerShell.

Sintassi

Add-Member
   -InputObject <PSObject>
   -TypeName <String>
   [-PassThru]
   [<CommonParameters>]
Add-Member
   -InputObject <PSObject>
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [-NotePropertyMembers] <IDictionary>
   [<CommonParameters>]
Add-Member
   -InputObject <PSObject>
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [-NotePropertyName] <String>
   [-NotePropertyValue] <Object>
   [<CommonParameters>]
Add-Member
   -InputObject <PSObject>
   [-MemberType] <PSMemberTypes>
   [-Name] <String>
   [[-Value] <Object>]
   [[-SecondValue] <Object>]
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [<CommonParameters>]

Descrizione

Il Add-Member cmdlet consente di aggiungere membri (proprietà e metodi) a un'istanza di un oggetto PowerShell. Ad esempio, è possibile aggiungere un membro NoteProperty contenente una descrizione dell'oggetto o un membro ScriptMethod che esegue uno script per modificare l'oggetto.

Per usare Add-Member, inviare tramite pipe l'oggetto a Add-Membero usare il parametro InputObject per specificare l'oggetto .

Il parametro MemberType indica il tipo di membro da aggiungere. Il parametro Name assegna un nome al nuovo membro e il parametro Value imposta il valore del membro.

Le proprietà e i metodi vengono aggiunti solo alla specifica istanza dell'oggetto indicata. Add-Member non modifica il tipo di oggetto. Per creare un nuovo tipo di oggetto, usare il Add-Type cmdlet .

È anche possibile usare il Export-Clixml cmdlet per salvare l'istanza dell'oggetto, inclusi i membri aggiuntivi, in un file. È quindi possibile usare il Import-Clixml cmdlet per ricreare l'istanza dell'oggetto dalle informazioni archiviate nel file esportato.

A partire da Windows PowerShell 3.0, Add-Member include nuove funzionalità che semplificano l'aggiunta di proprietà note agli oggetti. È possibile utilizzare i parametri NotePropertyName e NotePropertyValue per definire una proprietà note o usare il parametro NotePropertyMembers , che accetta una tabella hash di nomi e valori di proprietà note.

Inoltre, a partire da Windows PowerShell 3.0, il parametro PassThru , che genera un oggetto di output, è necessario meno frequentemente. Add-Member ora aggiunge i nuovi membri direttamente all'oggetto di input di altri tipi. Per altre informazioni, vedere la descrizione del parametro PassThru .

Esempio

Esempio 1: Aggiungere una proprietà note a un PSObject

Nell'esempio seguente viene aggiunta una proprietà Status note con un valore "Done" all'oggetto FileInfo che rappresenta il Test.txt file.

Il primo comando usa il Get-ChildItem cmdlet per ottenere un oggetto FileInfo che rappresenta il Test.txt file. Lo salva nella $a variabile .

Il secondo comando aggiunge la proprietà note all'oggetto in $a.

Il terzo comando usa la notazione punto per ottenere il valore della proprietà Status dell'oggetto in $a. Come illustrato nell'output, il valore è Done.

$A = Get-ChildItem c:\ps-test\test.txt
$A | Add-Member -NotePropertyName Status -NotePropertyValue Done
$A.Status

Done

Esempio 2: Aggiungere una proprietà alias a un PSObject

Nell'esempio seguente viene aggiunta una proprietà alias Size all'oggetto che rappresenta il Test.txt file. La nuova proprietà è un alias per la proprietà Length .

Il primo comando usa il Get-ChildItem cmdlet per ottenere l'oggetto Test.txt FileInfo .

Il secondo comando aggiunge la proprietà alias Size . Il terzo comando usa la notazione punto per ottenere il valore della nuova proprietà Size .

$A = Get-ChildItem C:\Temp\test.txt
$A | Add-Member -MemberType AliasProperty -Name Size -Value Length
$A.Size

2394

Esempio 3: Aggiungere una proprietà StringUse note a una stringa

In questo esempio la proprietà StringUse note viene aggiunta a una stringa. Poiché Add-Member non è possibile aggiungere tipi agli oggetti di input String , è possibile specificare il parametro PassThru per generare un oggetto di output. L'ultimo comando dell'esempio visualizza la nuova proprietà.

In questo esempio viene utilizzato il parametro NotePropertyMembers . Il valore del parametro NotePropertyMembers è una tabella hash. La chiave è il nome della proprietà della nota, StringUse e il valore è il valore della proprietà note, Display.

$A = "A string"
$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru
$A.StringUse

Display

Esempio 4: Aggiungere un metodo script a un oggetto FileInfo

In questo esempio viene aggiunto il metodo di script SizeInMB a un oggetto FileInfo che calcola le dimensioni del file al MegaByte più vicino. Il secondo comando crea uno ScriptBlock che usa il metodo statico Round dal [math] tipo per arrotondare le dimensioni del file alla seconda posizione decimale.

Il parametro Value usa anche la $This variabile automatica, che rappresenta l'oggetto corrente. La $This variabile è valida solo nei blocchi di script che definiscono nuove proprietà e metodi.

L'ultimo comando usa la notazione punto per chiamare il nuovo metodo di script SizeInMB sull'oggetto nella $A variabile .

$A = Get-ChildItem C:\Temp\test.txt
$S = {[math]::Round(($this.Length / 1MB), 2)}
$A | Add-Member -MemberType ScriptMethod -Name "SizeInMB" -Value $S
$A.SizeInMB()

0.43

Esempio 5: Creare un oggetto personalizzato

In questo esempio viene creato un oggetto personalizzato Asset .

Il New-Object cmdlet crea un PSObject salvato nella $Asset variabile. L'acceleratore [ordered] di tipi crea un dizionario ordinato archiviato nella $d variabile . Piping $Asset per Add-Member aggiungere le coppie chiave-valore nel dizionario all'oggetto come membri NoteProperty . Il parametro TypeName assegna il tipo Asset a PSObject. Il Get-Member cmdlet mostra il tipo e le proprietà dell'oggetto . Tuttavia, le proprietà sono elencate in ordine alfabetico, non nell'ordine in cui sono state aggiunte.

$Asset = New-Object -TypeName PSObject
$d = [ordered]@{Name="Server30"; System="Server Core"; PSVersion="4.0"}
$Asset | Add-Member -NotePropertyMembers $d -TypeName Asset
$Asset | Get-Member -MemberType Properties

TypeName: Asset

Name        MemberType   Definition
----        ----------   ----------
Name        NoteProperty string Name=Server30
PSVersion   NoteProperty string PSVersion=4.0
System      NoteProperty string System=Server Core

$Asset.PSObject.Properties | Format-Table Name, MemberType, TypeNameOfValue, Value

Name        MemberType TypeNameOfValue Value
----        ---------- --------------- -----
Name      NoteProperty System.String   Server30
System    NoteProperty System.String   Server Core
PSVersion NoteProperty System.String   4.0

Esaminando l'elenco non elaborato delle proprietà, vengono visualizzate le proprietà nell'ordine in cui sono state aggiunte all'oggetto . Format-Table viene usato in questo esempio per creare un output simile a Get-Member.

Esempio 6: Aggiungere un aliasProperty a un oggetto

In questo esempio viene creato un oggetto personalizzato che contiene due membri NoteProperty . Il tipo di noteProperty riflette il tipo del valore archiviato nella proprietà . In questo caso, la proprietà Age è una stringa.

PS> $obj = [pscustomobject]@{
      Name = 'Doris'
      Age = '20'
}
PS> $obj | Add-Member -MemberType AliasProperty -Name 'intAge' -Value age -SecondValue uint32
PS> $obj | Get-Member

   TypeName: System.Management.Automation.PSCustomObject

Name        MemberType    Definition
----        ----------    ----------
intAge      AliasProperty intAge = (System.UInt32)age
Equals      Method        bool Equals(System.Object obj)
GetHashCode Method        int GetHashCode()
GetType     Method        type GetType()
ToString    Method        string ToString()
Age         NoteProperty  string Age=20
Name        NoteProperty  string Name=Doris

PS> $obj

Name  Age intAge
----  --- ------
Doris 20      20

PS> $obj.Age + 1

201

PS> $obj.intAge + 1

21

La proprietà intAge è aliasProperty per la proprietà Age, ma il tipo è garantito che sia uint32.

Esempio 7: Aggiungere metodi get e set a un oggetto personalizzato

In questo esempio viene illustrato come definire i metodi Get e Set che accedono a una proprietà annidata in modo approfondito.

$user = [pscustomobject]@{
    Name      = 'User1'
    Age       = 29
    StartDate = [datetime]'2019-05-05'
    Position  = [pscustomobject]@{
        DepartmentName = 'IT'
        Role = 'Manager'
    }
}
$addMemberSplat = @{
    MemberType = 'ScriptProperty'
    Name = 'Title'
    Value = { $this.Position.Role }                  # getter
    SecondValue = { $this.Position.Role = $args[0] } # setter
}
$user | Add-Member @addMemberSplat
$user | Get-Member

TypeName: System.Management.Automation.PSCustomObject

Name        MemberType     Definition
----        ----------     ----------
Equals      Method         bool Equals(System.Object obj)
GetHashCode Method         int GetHashCode()
GetType     Method         type GetType()
ToString    Method         string ToString()
Age         NoteProperty   int Age=29
Name        NoteProperty   string Name=User1
Position    NoteProperty   System.Management.Automation.PSCustomObject Position=@{DepartmentName=IT; Role=Manager}
StartDate   NoteProperty   datetime StartDate=5/5/2019 12:00:00 AM
Title       ScriptProperty System.Object Title {get= $this.Position.Role ;set= $this.Position.Role = $args[0] ;}

$user.Title = 'Dev Manager'

Name      : User1
Age       : 29
StartDate : 5/5/2019 12:00:00 AM
Position  : @{DepartmentName=IT; Role=Dev Manager}
Title     : Dev Manager

Si noti che la proprietà Title è un oggetto ScriptProperty con un metodo Get e Set . Quando si assegna un nuovo valore alla proprietà Title, viene chiamato il metodo Set e viene modificato il valore della proprietà Role nella proprietà Position.

Parametri

-Force

Per impostazione predefinita, Add-Member non può aggiungere un nuovo membro se l'oggetto ha già un membro con lo stesso. Quando si usa il parametro Force , Add-Member sostituisce il membro esistente con il nuovo membro. Non è possibile usare il parametro Force per sostituire un membro standard di un tipo.

Tipo:SwitchParameter
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-InputObject

Specifica l'oggetto in cui viene aggiunto il nuovo membro. Immettere una variabile che contiene gli oggetti oppure digitare un comando o un'espressione che ottiene gli oggetti.

Tipo:PSObject
Posizione:Named
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:True
Accettare caratteri jolly:False

-MemberType

Specifica il tipo del membro da aggiungere. Questo parametro è obbligatorio. I valori validi per questo parametro sono:

  • AliasProperty
  • CodeMethod
  • CodeProperty
  • NotaProperty
  • ScriptMethod
  • ScriptProperty

Per informazioni su questi valori, vedere Enumerazione PSMemberTypes in PowerShell SDK.

No tutti gli oggetti hanno ogni tipo di membro. Se si specifica un tipo di membro che l'oggetto non ha, PowerShell restituisce un errore.

Tipo:PSMemberTypes
Alias:Type
Valori accettati:AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty
Posizione:0
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-Name

Specifica il nome del membro aggiunto da questo cmdlet.

Tipo:String
Posizione:1
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-NotePropertyMembers

Specifica una tabella hash o un dizionario ordinato che contiene una coppia chiave-valore che rappresenta i nomi NoteProperty e i relativi valori. Per altre informazioni sulle tabelle hash e sui dizionari ordinati in PowerShell, vedere about_Hash_Tables.

Questo parametro è stato introdotto in Windows PowerShell 3.0.

Tipo:IDictionary
Posizione:0
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-NotePropertyName

Specifica il nome della proprietà della nota.

Usare questo parametro con il parametro NotePropertyValue . Il parametro è facoltativo.

Questo parametro è stato introdotto in Windows PowerShell 3.0.

Tipo:String
Posizione:0
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-NotePropertyValue

Specifica il valore della proprietà note.

Usare questo parametro con il parametro NotePropertyName . Il parametro è facoltativo.

Questo parametro è stato introdotto in Windows PowerShell 3.0.

Tipo:Object
Posizione:1
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-PassThru

Restituisce un oggetto che rappresenta l'elemento in uso. Per impostazione predefinita, questo cmdlet non genera alcun output.

Per la maggior parte degli oggetti, Add-Member aggiunge i nuovi membri all'oggetto di input. Tuttavia, quando l'oggetto di input è una stringa, Add-Member non può aggiungere il membro all'oggetto di input. Per questi oggetti, utilizzare il parametro PassThru per creare un oggetto di output.

In Windows PowerShell 2.0 sono Add-Member stati aggiunti membri solo al wrapper PSObject di oggetti, non all'oggetto . Utilizzare il parametro PassThru per creare un oggetto di output per qualsiasi oggetto con un wrapper PSObject .

Tipo:SwitchParameter
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-SecondValue

Specifica informazioni aggiuntive facoltative sui membri AliasProperty, ScriptProperty o CodeProperty.

Se usato quando si aggiunge un aliasProperty, questo parametro deve essere un tipo di dati. Viene aggiunta una conversione al tipo di dati specificato al valore di AliasProperty. Ad esempio, se si aggiunge un aliasProperty che fornisce un nome alternativo per una proprietà stringa, è anche possibile specificare un parametro SecondValue di System.Int32 per indicare che il valore di tale proprietà stringa deve essere convertito in un numero intero quando si accede utilizzando l'aliasProperty corrispondente.

Per codeProperty, il valore deve essere un riferimento a un metodo che implementa una funzione di accesso Set. Utilizzare il GetMethod() metodo di un riferimento al tipo per ottenere un riferimento a un metodo. Il metodo deve accettare un singolo parametro che è un PSObject. La funzione di accesso Get viene assegnata usando il parametro Value .

Per uno ScriptProperty, il valore deve essere un blocco di script che implementa una funzione di accesso Set . La funzione di accesso Get viene assegnata usando il parametro Value .

Tipo:Object
Posizione:3
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-TypeName

Specifica un nome per il tipo.

Quando il tipo è una classe nello spazio dei nomi System o in un tipo con un acceleratore di tipo, è possibile immettere il nome breve del tipo. In caso contrario, è necessario immettere il nome completo del tipo. Questo parametro è valido solo quando InputObject è un PSObject.

Questo parametro è stato introdotto in Windows PowerShell 3.0.

Tipo:String
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-Value

Specifica il valore iniziale del membro aggiunto. Se si aggiunge un membro AliasProperty, CodeProperty o ScriptProperty, è possibile fornire informazioni aggiuntive usando il parametro SecondValue.

  • Per aliasProperty, il valore deve essere il nome della proprietà in corso di aliasing.
  • Per codeMethod, il valore deve essere un riferimento a un metodo. Utilizzare il GetMethod() metodo di un riferimento al tipo per ottenere un riferimento a un metodo.
  • Per codeProperty, il valore deve essere un riferimento a un metodo che implementa una funzione di accesso Get. Utilizzare il GetMethod() metodo di un riferimento al tipo per ottenere un riferimento a un metodo. riferimento. Il metodo deve accettare un singolo parametro che è un PSObject. La funzione di accesso Set viene assegnata usando il parametro SecondValue .
  • Per uno ScriptMethod, il valore deve essere un blocco di script.
  • Per uno ScriptProperty, il valore deve essere un blocco di script che implementa una funzione di accesso Get . La funzione di accesso Set viene assegnata usando il parametro SecondValue .
Tipo:Object
Posizione:2
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

Input

PSObject

È possibile inviare tramite pipe qualsiasi oggetto a questo cmdlet.

Output

None

Per impostazione predefinita, questo cmdlet non restituisce alcun output.

Object

Quando si usa il parametro PassThru , questo cmdlet restituisce il nuovo oggetto esteso.

Note

È possibile aggiungere membri solo agli oggetti di tipo PSObject . Per determinare se un oggetto è un oggetto PSObject , utilizzare l'operatore -is . Ad esempio, per testare un oggetto archiviato nella $obj variabile, digitare $obj -is [psobject].

Gli oggetti tipo PSObject mantengono l'elenco dei membri nell'ordine in cui i membri sono stati aggiunti all'oggetto.

I nomi dei parametri MemberType, Name, Value e SecondValue sono facoltativi. Se si omettono i nomi dei parametri, i valori dei parametri senza nome devono essere visualizzati in questo ordine: MemberType, Name, Value e SecondValue.

Se invece si includono i nomi, i parametri possono essere disposti in qualsiasi ordine.

È possibile usare la $this variabile automatica nei blocchi di script che definiscono i valori di nuove proprietà e metodi. La $this variabile fa riferimento all'istanza dell'oggetto a cui vengono aggiunte le proprietà e i metodi. Per altre informazioni sulla $this variabile, vedere about_Automatic_Variables.