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 cmdlet Add-Member consente di aggiungere membri (proprietà e metodi) a un'istanza di un oggetto PowerShell. Ad esempio, è possibile aggiungere un membro noteProperty che contiene 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-Memberoppure 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 aggiunti vengono aggiunti solo all'istanza specifica dell'oggetto specificato.
Add-Member non modifica il tipo di oggetto. Per creare un nuovo tipo di oggetto, usare il cmdlet Add-Type.
È anche possibile usare il cmdlet Export-Clixml per salvare l'istanza dell'oggetto, inclusi i membri aggiuntivi, in un file. È quindi possibile usare il cmdlet Import-Clixml 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 valori e nomi 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 più 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 il valore "Done" all'oggetto FileInfo che rappresenta il file di Test.txt.
Il primo comando usa il cmdlet Get-ChildItem per ottenere un oggetto FileInfo che rappresenta il file di Test.txt. Lo salva nella variabile $a.
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 file Test.txt. La nuova proprietà è un alias per la proprietà Length.
Il primo comando usa il cmdlet Get-ChildItem per ottenere l'oggettoFileInfo Test.txt.
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
Questo esempio aggiunge la proprietà stringUse a una stringa. Poiché Add-Member non può aggiungere tipi agli oggetti di input String, è possibile specificare il parametro PassThru per generare un oggetto di output. L'ultimo comando nell'esempio visualizza la nuova proprietà.
In questo esempio viene usato il parametro NotePropertyMembers. Il valore del parametro NotePropertyMembers è una tabella hash. La chiave è il nome della proprietà della nota, StringUsee 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 script SizeInMB a un oggetto FileInfo che calcola le dimensioni del file al MegaByte più vicino. Il secondo comando crea un ScriptBlock che usa il metodo statico Round dal tipo [math] per arrotondare le dimensioni del file alla seconda posizione decimale.
Il parametro Value usa anche la variabile automatica $This che rappresenta l'oggetto corrente. La variabile $This è valida solo nei blocchi di script che definiscono nuove proprietà e metodi.
L'ultimo comando usa la notazione punto per chiamare il nuovo metodo script SizeInMB sull'oggetto nella variabile $A.
$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 asset oggetto personalizzato.
Il cmdlet New-Object crea un PSObject salvato nella variabile $Asset. L'acceleratore di tipo [ordered] crea un dizionario ordinato archiviato nella variabile $d.
Il piping $Asset a Add-Member aggiunge le coppie chiave-valore nel dizionario all'oggetto come noteProperty membri.
parametro TypeName assegna il tipo Asset al PSObject. Il cmdlet Get-Member 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.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 NoteProperty membri. Il tipo per un 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
21La proprietà intAge è un AliasProperty per la proprietà age, ma è garantito che il tipo sia uint32.
Esempio 7: Aggiungere metodi get e set a un oggetto personalizzato
In questo esempio viene illustrato come definire Get e Set metodi 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 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 a cui viene aggiunto il nuovo membro. Immettere una variabile contenente 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 accettabili per questo parametro sono:
- AliasProperty
- CodeMethod
- CodeProperty
- NotaProperty
- ScriptMethod
- ScriptProperty
Per informazioni su questi valori, vedere di enumerazione PSMemberTypes in PowerShell SDK.
Non 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 NoteProperty nomi 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. Questo 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. Questo 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 con cui si sta lavorando. 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 Add-Member aggiunti membri solo al PSObject wrapper di oggetti, non all'oggetto . Utilizzare il parametro PassThru per creare un oggetto di output per qualsiasi oggetto con PSObject wrapper.
| Tipo: | SwitchParameter |
| Posizione: | Named |
| Valore predefinito: | None |
| Necessario: | False |
| Accettare l'input della pipeline: | False |
| Accettare caratteri jolly: | False |
-SecondValue
Specifica informazioni aggiuntive facoltative su AliasProperty, ScriptPropertyo membri 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 dell'AliasProperty. Se ad esempio 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 un CodeProperty, il valore deve essere un riferimento a un metodo che implementa una funzione di accesso Set. Utilizzare il metodo GetMethod() di un riferimento al tipo per ottenere un riferimento a un metodo. Il metodo deve accettare un singolo parametro PSObject. La funzione di accesso Get viene assegnata usando il parametro Value.
Per un 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 il nome completo del tipo. Questo parametro è efficace solo quando il 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 AliasProperty, CodePropertyo membro ScriptProperty, è possibile fornire informazioni aggiuntive usando il parametro SecondValue.
- Per un AliasProperty, il valore deve essere il nome della proprietà in corso di aliasing.
- Per un CodeMethod, il valore deve essere un riferimento a un metodo. Utilizzare il metodo
GetMethod()di un riferimento al tipo per ottenere un riferimento a un metodo. - Per un CodeProperty, il valore deve essere un riferimento a un metodo che implementa una funzione di accesso Get. Utilizzare il metodo
GetMethod()di un riferimento al tipo per ottenere un riferimento a un metodo. riferimento. Il metodo deve accettare un singolo parametro PSObject. La funzione di accesso set set di viene assegnata usando il parametro SecondValue. - Per un ScriptMethod, il valore deve essere un blocco di script.
- Per un ScriptProperty, il valore deve essere un blocco di script che implementa una funzione di accesso get . La funzione di accesso set set di 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 l'oggetto esteso appena esteso.
Note
È possibile aggiungere membri solo a oggetti di tipo PSObject. Per determinare se un oggetto è un oggetto PSObject, utilizzare l'operatore -is. Ad esempio, per testare un oggetto archiviato nella variabile $obj, 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 MemberType, Name, Valuee parametri secondValue sono facoltativi. Se si omettono i nomi dei parametri, i valori dei parametri senza nome devono essere visualizzati in questo ordine: MemberType, Name, Valuee SecondValue.
Se si includono i nomi dei parametri, i parametri possono essere visualizzati in qualsiasi ordine.
È possibile usare la variabile automatica $this nei blocchi di script che definiscono i valori di nuove proprietà e metodi. La variabile $this fa riferimento all'istanza dell'oggetto a cui vengono aggiunte le proprietà e i metodi. Per altre informazioni sulla variabile $this, vedere about_Automatic_Variables.
