Condividi tramite

Add-Member

  • Riferimento
Modulo:
Microsoft.PowerShell.Utility

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

Sintassi

Add-Member
   -InputObject <PSObject>
   -TypeName <String>
   [-PassThru]
   [<CommonParameters>]
Add-Member
   [-NotePropertyMembers] <IDictionary>
   -InputObject <PSObject>
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [<CommonParameters>]
Add-Member
   [-NotePropertyName] <String>
   [-NotePropertyValue] <Object>
   -InputObject <PSObject>
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [<CommonParameters>]
Add-Member
   [-MemberType] <PSMemberTypes>
   [-Name] <String>
   [[-Value] <Object>]
   [[-SecondValue] <Object>]
   -InputObject <PSObject>
   [-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 , inviare Add-Membertramite pipe l'oggetto a Add-Membero utilizzare 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 usare i parametri NotePropertyName e NotePropertyValue per definire una proprietà di nota o il parametro NotePropertyMembers, che accetta una tabella hash di nomi e valori di proprietà di nota.

Inoltre, a partire da Windows PowerShell 3.0, il parametro PassThru, che genera un oggetto di output, è meno necessario. Add-Member aggiunge ora 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à nota a un PSObject

Nell'esempio seguente viene aggiunta una proprietà Status note con il 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.txtFileInfo .

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à Note StringUse a una stringa

In questo esempio viene aggiunta la proprietà Note StringUse 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: Copiare tutte le proprietà di un oggetto in un altro

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

Il foreach ciclo usa il Get-Member cmdlet per ottenere ognuna delle proprietà dell'oggetto From . I comandi all'interno del foreach ciclo vengono eseguiti in serie su ognuna delle proprietà.

Il Add-Member comando aggiunge la proprietà dell'oggetto From all'oggetto To come NotaProperty. Il valore viene copiato usando il parametro Value . Usa il parametro Force per aggiungere membri con lo stesso nome del membro.

function Copy-Property ($From, $To)
{
    $properties = Get-Member -InputObject $From -MemberType Property
    foreach ($p in $properties)
    {
        $To | Add-Member -MemberType NoteProperty -Name $p.Name -Value $From.$($p.Name) -Force
    }
}

Esempio 6: Create un oggetto personalizzato

In questo esempio viene creato un oggetto personalizzato Asset .

Il New-Object cmdlet crea un PSObject. Nell'esempio viene salvato l'oggetto PSObject nella $Asset variabile .

Il secondo comando usa l'acceleratore [ordered] di tipi per creare un dizionario ordinato di nomi e valori. Il comando salva il risultato nella $D variabile .

Il terzo comando usa il parametro NotePropertyMembers del Add-Member cmdlet per aggiungere il dizionario nella $D variabile a PSObject. La proprietà TypeName assegna un nuovo nome, Asset, a PSObject.

L'ultimo comando invia tramite pipe il nuovo oggetto Asset al Get-Member cmdlet . L'output mostra che l'oggetto ha un nome di tipo Asset e le proprietà note definite nel dizionario ordinato.

$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

TypeName: Asset

Name        MemberType   Definition
----        ----------   ----------
Equals      Method       bool Equals(System.Object obj)
GetHashCode Method       int GetHashCode()
GetType     Method       type GetType()
ToString    Method       string ToString()
Name        NoteProperty System.String Name=Server30
PSVersion   NoteProperty System.String PSVersion=4.0
System      NoteProperty System.String System=Server Core

Parametri

-Force

Indica che questo cmdlet aggiunge un nuovo membro anche l'oggetto ha un membro personalizzato con lo stesso nome. Non è possibile utilizzare il parametro Force per sostituire un membro standard di un tipo.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:PSObject
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-MemberType

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

  • NotaProperty
  • AliasProperty
  • ScriptProperty
  • Codeproperty
  • ScriptMethod
  • CodeMethod

Per informazioni su questi valori, vedere Enumerazione PSMemberTypes in MSDN Library.

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

Type:PSMemberTypes
Aliases:Type
Accepted values:AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Name

Specifica il nome del membro aggiunto da questo cmdlet.

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NotePropertyMembers

Specifica una tabella hash o un dizionario ordinato di nomi e valori di proprietà di nota. Immettere la tabella hash o il dizionario in cui le chiavi sono nomi di proprietà di nota e i valori sono valori di proprietà di nota.

Per altre informazioni sulle tabelle hash e i dizionari ordinati in PowerShell, vedere about_Hash_Tables.

Questo parametro è stato introdotto in Windows PowerShell 3.0.

Type:IDictionary
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NotePropertyName

Specifica il nome della proprietà della nota.

Usare questo parametro con il parametro NotePropertyValue. Questo parametro è facoltativo e,

Questo parametro è stato introdotto in Windows PowerShell 3.0.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NotePropertyValue

Specifica il valore della proprietà nota.

Usare questo parametro con il parametro NotePropertyName . Questo parametro è facoltativo e,

Questo parametro è stato introdotto in Windows PowerShell 3.0.

Type:Object
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

Restituisce un oggetto che rappresenta l'elemento in uso. Per impostazione predefinita, il 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, usare il parametro PassThru per creare un oggetto di output.

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SecondValue

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

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.

È possibile usare il parametro SecondValue per specificare un elemento ScriptBlock aggiuntivo quando si aggiunge un membro ScriptProperty . Il primo ScriptBlock, specificato nel parametro Value , viene usato per ottenere il valore di una variabile. Il secondo ScriptBlock, specificato nel parametro SecondValue , viene usato per impostare il valore di una variabile.

Type:Object
Position:3
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Value

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

Type:Object
Position:2
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Input

PSObject

È possibile inviare tramite pipe qualsiasi tipo di oggetto a questo cmdlet.

Output

None or System.Object

Quando si usa il parametro PassThru , questo cmdlet restituisce l'oggetto appena esteso. In caso contrario, il cmdlet non genera alcun output.

Note

È possibile aggiungere membri solo agli oggetti 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].

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.