Add-Member

Aggiunge un membro personalizzato definito dall'utente a un'istanza di un oggetto di Windows PowerShell.

Sintassi

Add-Member [-MemberType] {<AliasProperty> | <CodeProperty> | <Property> | <NoteProperty> | <ScriptProperty> | <Properties> | <PropertySet> | <Method> | <CodeMethod> | <ScriptMethod> | <Methods> | <ParameterizedProperty> | <MemberSet> | <Event> | <All>} [-Name] <string> -InputObject <psobject> [[-Value] <Object>] [[-SecondValue] <Object>] [-Force] [-PassThru] [<CommonParameters>]

Descrizione

Il cmdlet Add-Member aggiunge un membro personalizzato definito dall'utente a un'istanza di un oggetto di Windows PowerShell. Consente di aggiungere i seguenti tipi di membri: AliasProperty, CodeProperty, NoteProperty, ScriptProperty, PropertySet, CodeMethod, MemberSet e ScriptMethod. Per impostare il valore iniziale del membro, viene utilizzato il parametro Value. Nel caso di AliasProperty, ScriptProperty, CodeProperty e CodeMethod, è possibile specificare ulteriori informazioni utilizzando il parametro SecondValue.

I membri vengono aggiunti all'istanza specifica dell'oggetto reindirizzato a Add-Member o specificato tramite il parametro InputObject. Il membro aggiuntivo è disponibile solo finché l'istanza è disponibile. È possibile utilizzare il cmdlet Export-Clixml per salvare in un file l'istanza e i membri aggiuntivi. Le informazioni archiviate in tale file possono essere utilizzate dal cmdlet Import-Clixml per creare nuovamente l'istanza dell'oggetto.

Parametri

-Force

Aggiunge un nuovo membro anche se ne esiste già uno con lo stesso nome. Non funziona con i membri principali di un tipo.

-InputObject <psobject>

Specifica l'oggetto a cui verrà aggiunto il nuovo membro. Immettere una variabile contenente gli oggetti oppure digitare un comando o un'espressione che consente di ottenere gli oggetti.

-MemberType <PSMemberTypes>

Specifica il tipo del membro da aggiungere. Questo parametro è obbligatorio.

I valori validi per questo parametro sono:

-- AliasProperty: proprietà che definisce un nuovo nome per una proprietà esistente.

-- CodeMethod: metodo che fa riferimento a un metodo statico di una classe Microsoft .NET Framework.

-- CodeProperty: proprietà che fa riferimento a una proprietà statica di una classe .NET Framework.

-- MemberSet: raccolta predefinita di proprietà e metodi, quali PSBase, PSObject e PSTypeNames.

-- Method: metodo dell'oggetto .NET Framework sottostante.

-- NoteProperty: proprietà con un valore statico.

-- ParameterizedProperty: proprietà che accetta parametri e valori di parametro.

-- Property: proprietà dell'oggetto .NET Framework sottostante.

-- PropertySet: raccolta predefinita di proprietà dell'oggetto.

-- ScriptMethod: metodo il cui valore è l'output di uno script.

-- ScriptProperty: proprietà il cui valore è l'output di uno script.

-- All: ottiene tutti i tipi di membro.

-- Methods: ottiene tutti i tipi di metodo dell'oggetto (ad esempio method, codemethod, scriptmethod)

-- Properties: ottiene tutti i tipi di proprietà dell'oggetto (ad esempio property, codeproperty, aliasproperty, scriptproperty).

Non tutti gli oggetti dispongono di ogni tipo di membro. Se si specifica un tipo di membro di cui l'oggetto non dispone, Windows PowerShell restituisce un errore.

Il tipo di membro Event non è valido per Add-Member.

-Name <string>

Specifica il nome del membro da aggiungere.

Se si omette il nome del parametro "Name", il valore del parametro -Name deve essere il secondo valore di parametro senza nome nel comando. Se si include il nome del parametro, i parametri possono essere riportati in qualsiasi ordine.

-PassThru

Passa l'oggetto appena esteso alla pipeline. Per impostazione predefinita, il cmdlet non genera alcun output.

-SecondValue <Object>

Specifica ulteriori informazioni facoltative sui membri AliasProperty, ScriptProperty, CodeProperty o CodeMethod. Se viene utilizzato quando si aggiunge un membro AliasProperty, questo parametro deve essere un tipo di dati. Al valore di AliasProperty verrà aggiunta una conversione (cast) nel tipo di dati specificato. Se ad esempio si aggiunge un membro AliasProperty che fornisce un nome alternativo per una proprietà di stringa, è inoltre possibile specificare un parametro SecondValue di System.Int32 per indicare che il valore di tale proprietà di stringa deve essere convertito in un valore integer quando per l'accesso viene utilizzato il membro AliasProperty corrispondente.

È possibile utilizzare il parametro SecondValue per specificare un membro ScriptBlock aggiuntivo quando si aggiunge un membro ScriptProperty. In tal caso, il primo membro ScriptBlock, specificato nel parametro Value, viene utilizzato per ottenere il valore di una variabile. Il secondo membro ScriptBlock, specificato nel parametro SecondValue, viene utilizzato per impostare il valore di una variabile.

-Value <Object>

Specifica il valore iniziale del membro aggiunto. Se si aggiunge un membro AliasProperty, CodeProperty o CodeMethod, è possibile specificare ulteriori informazioni facoltative utilizzando il parametro SecondValue.

<CommonParameters>

Questo cmdlet supporta i parametri comuni -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Per ulteriori informazioni, vedere about_Commonparameters.

Input e output

Il tipo di input è il tipo degli oggetti che è possibile reindirizzare al cmdlet. Il tipo restituito è il tipo degli oggetti restituiti dal cmdlet.

Note

È possibile aggiungere membri solo a oggetti PSObject. Per determinare se un oggetto è un oggetto PSObject, utilizzare l'operatore "is". Per testare ad esempio un oggetto archiviato nella variabile $obj, digitare "$obj -is [PSObject]".

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 riportati nell'ordine seguente: MemberType, Name, Value, SecondValue. Se si includono i nomi dei parametri, i parametri possono essere riportati in qualsiasi ordine.

Esempio 1

C:\PS>$a = (get-childitem)[0]

C:\PS> $a | add-member -membertype noteproperty -name Status -value done

C:\PS> $a | get-member -type noteproperty

   TypeName: System.IO.DirectoryInfo

Name          MemberType   Definition
----          ----------   ----------
PSChildName   NoteProperty System.String PSChildName=Co
PSDrive       NoteProperty System.Management.Automation
PSIsContainer NoteProperty System.Boolean PSIsContainer
PSParentPath  NoteProperty System.String PSParentPath=M
PSPath        NoteProperty System.String PSPath=Microso
PSProvider    NoteProperty System.Management.Automation
Status        NoteProperty System.String Status=done

Descrizione
-----------
Questi comandi aggiungono la proprietà di nota Status a un oggetto DirectoryInfo restituito da Get-ChildItem e assegnano a essa un valore "done". 

Il primo comando ottiene il primo oggetto restituito da Get-Childitem (indice 0).

Il secondo comando aggiunge la proprietà di nota.

Il terzo comando utilizza un operatore pipeline (|) per inviare l'oggetto aggiornato al cmdlet Get-Member. L'output mostra che la proprietà è stata aggiunta.

Esempio 2

C:\PS>$a = (get-childitem)[0]

C:\PS> $a | add-member -membertype aliasproperty -name FileLength -value Length 

C:\PS> $a.filelength

Descrizione
-----------
Con questi comandi viene aggiunta la proprietà alias FileLength a un oggetto DirectoryInfo restituito da Get-ChildItem. La nuova proprietà è un alias della proprietà Length. 

Il primo comando ottiene il primo oggetto restituito da Get-Childitem (indice 0).

Il secondo comando aggiunge la proprietà alias.

Il terzo comando restituisce il valore della nuova proprietà FileLength.

Esempio 3

C:\PS>$a = "a string"

C:\PS> $a = $a | add-member -membertype noteproperty -name StringUse -value Display -passthru

C:\PS> $a.StringUse

Descrizione
-----------
Questi comandi aggiungono la proprietà StringUse a una stringa. Poiché la stringa non è un oggetto PSObject, è necessario includere il parametro PassThru nel comando per salvare la stringa estesa nella variabile. Con l'ultimo comando nell'esempio viene visualizzata la nuova proprietà.

Esempio 4

C:\PS>$a = "this is a string"

C:\PS> $a = add-member -inputobject $a -membertype scriptmethod -name words `
-value {$this.split()} -passthru

C:\PS> $a.words()

Descrizione
-----------
Con questi comandi viene aggiunto un metodo script a un oggetto stringa. Il metodo script esporrà il metodo Split() della classe System.String della libreria di classi .NET Framework per agevolare la restituzione delle singole parole in una stringa mediante la chiamata a un metodo denominato "Words" nell'oggetto stringa. Si noti che per forzare Add-Member a restituire l'oggetto stringa esteso come output da archiviare nella variabile $a, viene utilizzato il parametro PassThru.

Esempio 5

C:\PS>$event = get-eventlog -logname system -newest 1

C:\PS> $event.TimeWritten | get-member

C:\PS> add-member -inputobject $event -membertype aliasproperty -name When `
-value TimeWritten -secondvalue System.String

C:\PS> $event.When | get-member

Descrizione
-----------
Tramite questi comandi una proprietà AliasProperty viene aggiunta a un oggetto EventLogEntry restituito dai cmdlet Get-EventLog. Il nome della proprietà AliasProperty è "When" e rappresenta un alias della proprietà TimeWritten dell'oggetto. Verrà quindi utilizzato il parametro SecondValue per specificare che il valore della proprietà deve essere convertito nel tipo System.String quando l'accesso viene effettuato tramite AliasProperty. La proprietà TimeWritten è un oggetto DateTime.

Nel primo comando viene utilizzato il cmdlet Get-EventLog per recuperare dal registro eventi di sistema l'evento più recente che viene quindi archiviato nella variabile $event. 

Il secondo comando accede alla proprietà TimeWritten di tale evento e la reindirizza al cmdlet Get-Member per dimostrare che la proprietà è un tipo DateTime. Add-Member viene quindi utilizzato per aggiungere un membro AliasProperty all'istanza dell'oggetto EventLogEntry archiviato nella variabile $event. Vengono quindi utilizzati il parametro Name per impostare il nome del nuovo membro su "When" e il parametro Value per specificare che si tratta di un alias della proprietà 'TimeWritten'. Viene infine utilizzato il parametro SecondValue per indicare che, quando verrà utilizzato il nuovo membro, sarà necessario eseguire il cast del valore restituito dal relativo tipo System.DateTime originale in un tipo System.String. 

Nel terzo del comando viene effettuato l'accesso al nuovo membro che viene reindirizzato al cmdlet Get-Member per confermare che il tipo del membro è System.String.

Esempio 6

C:\PS>function Copy-Property ($From, $To)

{
  foreach ($p in Get-Member -InputObject $From -MemberType Property)
  {
     Add-Member -InputObject $To -MemberType NoteProperty -Name $p.Name 
     -Value $From.$($p.Name) -Force

     $To.$($p.Name) = $From.$($p.Name)
   }
}

Descrizione
-----------
Questa funzione copia tutte le proprietà di un oggetto in un altro oggetto.

Nel primo comando della funzione viene dichiarato il nome della funzione e ne vengono elencati i parametri. 

Nel ciclo Foreach viene utilizzato il cmdlet Get-Member per ottenere ogni proprietà dell'oggetto From. I comandi nel ciclo Foreach vengono eseguiti in serie per ogni proprietà.

Con il comando Add-Member la proprietà dell'oggetto From viene aggiunta all'oggetto To come NoteProperty. Viene utilizzato il parametro Force per consentire al comando di aggiungere membri con lo stesso nome di membro.

L'ultimo comando della funzione fornisce alla nuova proprietà lo stesso nome della proprietà originale.

Vedere anche

Concetti

Get-Member
Export-Clixml
Import-Clixml