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
DoneEsempio 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
2394Esempio 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
DisplayEsempio 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.43Esempio 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
$Asset | Add-Member -NotePropertyMembers @{Name="Server30"} -TypeName Asset
$Asset | Add-Member -NotePropertyMembers @{System="Server Core"}
$Asset | Add-Member -NotePropertyMembers @{PSVersion="4.0"}
$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.0Esaminando 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 : Doris
Age : 20
intAge : 20
PS> $obj.Age + 1
201
PS> $obj.intAge + 1
21La 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 ManagerSi 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
È possibile inviare tramite pipe qualsiasi oggetto a questo cmdlet.
Output
None
Per impostazione predefinita, questo cmdlet non restituisce alcun output.
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.
