about_Types.ps1xml

Articolo
04/13/2023

Descrizione breve

Illustra come usare Types.ps1xml i file per estendere i tipi di oggetti usati in PowerShell.

Descrizione lunga

I dati dei tipi estesi definiscono proprietà e metodi aggiuntivi ("membri") dei tipi di oggetto in PowerShell. Esistono due tecniche per l'aggiunta di dati di tipo esteso a una sessione di PowerShell.

Types.ps1xml file: file XML che definisce i dati di tipo esteso.
Update-TypeData: cmdlet che ricarica i Types.ps1xml file e definisce i dati estesi per i tipi nella sessione corrente.

In questo argomento vengono descritti i Types.ps1xml file. Per altre informazioni sull'uso del Update-TypeData cmdlet per aggiungere dati di tipo esteso dinamico alla sessione corrente, vedere Update-TypeData.

Informazioni sui dati dei tipi estesi

I dati dei tipi estesi definiscono proprietà e metodi aggiuntivi ("membri") dei tipi di oggetto in PowerShell. È possibile estendere qualsiasi tipo supportato da PowerShell e usare le proprietà e i metodi aggiunti nello stesso modo in cui si usano le proprietà definite nei tipi di oggetto.

Ad esempio, PowerShell aggiunge una proprietà DateTime a tutti gli System.DateTime oggetti, ad esempio quelli restituiti dal Get-Date cmdlet.

(Get-Date).DateTime

Sunday, January 29, 2012 9:43:57 AM

La proprietà DateTime non verrà trovata nella descrizione della struttura System.DateTime, perché PowerShell aggiunge la proprietà ed è visibile solo in PowerShell.

PowerShell definisce internamente un set predefinito di tipi estesi. Queste informazioni sul tipo vengono caricate in ogni sessione di PowerShell all'avvio. La proprietà DateTime fa parte di questo set predefinito. Prima di PowerShell 6, le definizioni dei tipi sono state archiviate nel Types.ps1xml file nella directory di installazione di PowerShell ($PSHOME).

Aggiunta di dati di tipo esteso a PowerShell

Esistono tre origini di dati di tipo esteso nelle sessioni di PowerShell.

I dati dei tipi estesi vengono definiti da PowerShell e caricati automaticamente in ogni sessione di PowerShell. A partire da PowerShell 6, queste informazioni vengono compilate in PowerShell e non vengono più fornite in un Types.ps1xml file.
I Types.ps1xml file che i moduli esportano vengono caricati quando il modulo viene importato nella sessione corrente.
I dati dei tipi estesi definiti tramite il Update-TypeData cmdlet vengono aggiunti solo alla sessione corrente. Non viene salvato in un file.

Nella sessione i dati del tipo esteso delle tre origini vengono applicati agli oggetti nello stesso modo e sono disponibili in tutti gli oggetti dei tipi specificati.

Cmdlet TypeData

I cmdlet seguenti sono inclusi nel modulo Microsoft.PowerShell.Utility in PowerShell 3.0 e versioni successive.

Get-TypeData: ottiene i dati del tipo esteso nella sessione corrente.
Update-TypeData: ricarica i Types.ps1xml file. Aggiunge dati di tipo estesi alla sessione corrente.
Remove-TypeData: rimuove i dati del tipo esteso dalla sessione corrente.

Per altre informazioni su questi cmdlet, vedere l'argomento della Guida per ogni cmdlet.

File Types.ps1xml predefiniti

I Types.ps1xml file nella $PSHOME directory vengono aggiunti automaticamente a ogni sessione.

Il Types.ps1xml file nella directory di installazione di PowerShell ($PSHOME) è un file di testo basato su XML che consente di aggiungere proprietà e metodi agli oggetti usati in PowerShell. PowerShell include file predefiniti Types.ps1xml che aggiungono diversi elementi ai tipi .NET, ma è possibile creare file aggiuntivi Types.ps1xml per estendere ulteriormente i tipi.

Per impostazione predefinita, ad esempio, gli oggetti matrice (System.Array) hanno una proprietà Length che elenca il numero di oggetti nella matrice. Tuttavia, poiché il nome Length non descrive chiaramente la proprietà, PowerShell aggiunge una proprietà alias denominata Count che visualizza lo stesso valore. Il codice XML seguente aggiunge la proprietà Count al System.Array tipo .

<Type>
  <Name>System.Array</Name>
  <Members>
    <AliasProperty>
      <Name>Count</Name>
      <ReferencedMemberName>
        Length
      </ReferencedMemberName>
    </AliasProperty>
  </Members>
</Type>

Per ottenere il nuovo AliasProperty, usare un Get-Member comando in qualsiasi matrice, come illustrato nell'esempio seguente.

Get-Member -InputObject (1,2,3,4)

Il comando restituisce i risultati seguenti.

Name       MemberType    Definition
----       ----------    ----------
Count      AliasProperty Count = Length
Address    Method        System.Object& Address(Int32)
Clone      Method        System.Object Clone()
CopyTo     Method        System.Void CopyTo(Array array, Int32 index):
Equals     Method        System.Boolean Equals(Object obj)
Get        Method        System.Object Get(Int32)
# ...

Di conseguenza, è possibile usare la proprietà Count o la proprietà Length delle matrici in PowerShell. Ad esempio:

(1, 2, 3, 4).count
4

(1, 2, 3, 4).length
4

Creazione di nuovi file Types.ps1xml

I .ps1xml file installati con PowerShell sono firmati digitalmente per evitare manomissioni perché la formattazione può includere blocchi di script. Pertanto, per aggiungere una proprietà o un metodo a un tipo .NET, creare file personalizzati Types.ps1xml e quindi aggiungerli alla sessione di PowerShell.

Per creare un nuovo file, iniziare copiando un file esistente Types.ps1xml . Il nuovo file può avere qualsiasi nome, ma deve avere un'estensione di .ps1xml file. È possibile inserire il nuovo file in qualsiasi directory accessibile a PowerShell, ma è utile inserire i file nella directory di installazione di PowerShell ($PSHOME) o in una sottodirectory della directory di installazione.

Dopo aver salvato il nuovo file, usare il Update-TypeData cmdlet per aggiungere il nuovo file alla sessione di PowerShell. Se si vuole che i tipi hanno la precedenza sui tipi predefiniti definiti, usare il parametro PrependData del Update-TypeData cmdlet . Update-TypeData influisce solo sulla sessione corrente. Per apportare la modifica a tutte le sessioni future, esportare la console o aggiungere il Update-TypeData comando al profilo di PowerShell.

Types.ps1xml e Add-Member

I Types.ps1xml file aggiungono proprietà e metodi a tutte le istanze degli oggetti del tipo .NET specificato nella sessione di PowerShell interessata. Tuttavia, se è necessario aggiungere proprietà o metodi solo a un'istanza di un oggetto, usare il Add-Member cmdlet .

Per altre informazioni, vedere Add-Member.

Esempio: Aggiunta di un membro Age agli oggetti FileInfo

In questo esempio viene illustrato come aggiungere una proprietà Age agli oggetti System.IO.FileInfo . L'età di un file è la differenza tra l'ora di creazione e l'ora corrente in giorni.

Poiché la proprietà Age viene calcolata usando un blocco di script, trovare un <ScriptProperty> tag da usare come modello per la nuova proprietà Age .

Salvare il codice XML seguente nel file $PSHOME\MyTypes.ps1xml.

<?xml version="1.0" encoding="utf-8" ?>
<Types>
  <Type>
    <Name>System.IO.FileInfo</Name>
    <Members>
      <ScriptProperty>
        <Name>Age</Name>
        <GetScriptBlock>
          ((Get-Date) - ($this.CreationTime)).Days
        </GetScriptBlock>
      </ScriptProperty>
    </Members>
  </Type>
</Types>

Eseguire Update-TypeData per aggiungere il nuovo Types.ps1xml file alla sessione corrente. Il comando usa il parametro PrependData per inserire il nuovo file in un ordine di precedenza superiore rispetto alle definizioni originali.

Per altre informazioni su Update-TypeData, vedere Update-TypeData.

Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml

Per testare la modifica, eseguire un Get-ChildItem comando per ottenere il file PowerShell.exe nella $PSHOME directory e quindi inviare tramite pipe il file al Format-List cmdlet per elencare tutte le proprietà del file. In seguito alla modifica, la proprietà Age viene visualizzata nell'elenco.

Get-ChildItem $PSHOME\pwsh.exe | Select-Object Age

XML nei file Types.ps1xml

La definizione completa dello schema è disponibile in Types.xsd nel repository del codice sorgente di PowerShell in GitHub.

Il <Types> tag racchiude tutti i tipi definiti nel file. Dovrebbe essere presente un <Types> solo tag.

Ogni tipo .NET indicato nel file deve essere rappresentato da un <Type> tag.

I tag di tipo devono contenere i tag seguenti:

<Name>: racchiude il nome del tipo .NET interessato.

<Members>: racchiude i tag per le nuove proprietà e i nuovi metodi definiti per il tipo .NET.

Uno dei tag membro seguenti può trovarsi all'interno del <Members> tag .

AliasProperty

Definisce un nuovo nome per una proprietà esistente.

Il <AliasProperty> tag deve avere un <Name> tag che specifica il nome della nuova proprietà e un <ReferencedMemberName> tag che specifica la proprietà esistente.

Ad esempio, la proprietà Alias Count è un alias per la proprietà Length degli oggetti matrice.

<Type>
  <Name>System.Array</Name>
  <Members>
    <AliasProperty>
      <Name>Count</Name>
      <ReferencedMemberName>Length</ReferencedMemberName>
    </AliasProperty>
  </Members>
</Type>

CodeMethod

Fa riferimento a un metodo statico di una classe .NET.

Il <CodeMethod> tag deve avere un <Name> tag che specifica il nome del nuovo metodo e un <CodeReference> tag che specifica il codice in cui è definito il metodo.

Ad esempio, il metodo ToString è il nome della definizione di codice Microsoft.PowerShell.ToStringCodeMethods .

  <Type>
    <Name>System.Xml.XmlNode</Name>
    <Members>
      <CodeMethod>
        <Name>ToString</Name>
        <CodeReference>
          <TypeName>Microsoft.PowerShell.ToStringCodeMethods</TypeName>
          <MethodName>XmlNode</MethodName>
        </CodeReference>
      </CodeMethod>
    </Members>
  </Type>

Codeproperty

Fa riferimento a un metodo statico di una classe .NET.

Il <CodeProperty> tag deve avere un <Name> tag che specifica il nome della nuova proprietà e un <GetCodeReference> tag che specifica il codice in cui viene definita la proprietà.

Ad esempio, la proprietà Mode degli oggetti è una proprietà di System.IO.DirectoryInfo codice definita nel provider FileSystem di PowerShell.

<Type>
  <Name>System.IO.DirectoryInfo</Name>
  <Members>
    <CodeProperty>
      <Name>Mode</Name>
      <GetCodeReference>
        <TypeName>
          Microsoft.PowerShell.Commands.FileSystemProvider
        </TypeName>
        <MethodName>Mode</MethodName>
      </GetCodeReference>
    </CodeProperty>
  </Members>
</Type>

MemberSet

Definisce una raccolta di membri (proprietà e metodi).

I <MemberSet> tag vengono visualizzati all'interno dei tag primari <Members> . I tag devono racchiudere un <Name> tag che circonda il nome del set di membri e un tag secondario <Members> che racchiudono i membri (proprietà e metodi) nel set. Uno qualsiasi dei tag che creano una proprietà (ad esempio <NoteProperty> o <ScriptProperty>) o un metodo (ad esempio <Method> o <ScriptMethod>) può essere membri del set.

Nei Types.ps1xml file il <MemberSet> tag viene usato per definire le visualizzazioni predefinite degli oggetti .NET in PowerShell. In questo caso, il nome del set di membri (il valore all'interno dei <Name> tag) è sempre PsStandardMembers e i nomi delle proprietà (il valore del <Name> tag) sono uno dei seguenti:

DefaultDisplayProperty: singola proprietà di un oggetto .
DefaultDisplayPropertySet: una o più proprietà di un oggetto .
DefaultKeyPropertySet: una o più proprietà chiave di un oggetto . Una proprietà chiave identifica le istanze dei valori delle proprietà, ad esempio il numero ID di elementi in una cronologia di sessione.

Ad esempio, il codice XML seguente definisce la visualizzazione predefinita dei servizi (System.ServiceProcess.ServiceController oggetti) restituiti dal Get-Service cmdlet . Definisce un set di membri denominato PsStandardMembers costituito da una proprietà predefinita impostata con le proprietà Status, Name e DisplayName .

<Type>
  <Name>System.ServiceProcess.ServiceController</Name>
  <Members>
    <MemberSet>
      <Name>PSStandardMembers</Name>
      <Members>
        <PropertySet>
          <Name>DefaultDisplayPropertySet</Name>
          <ReferencedProperties>
            <Name>Status</Name>
            <Name>Name</Name>
            <Name>DisplayName</Name>
          </ReferencedProperties>
        </PropertySet>
      </Members>
    </MemberSet>
  </Members>
</Type>

<Method>: fa riferimento a un metodo nativo dell'oggetto sottostante.

<Methods>: raccolta dei metodi dell'oggetto .

NotaProperty

Definisce una proprietà con un valore statico.

Il <NoteProperty> tag deve avere un <Name> tag che specifica il nome della nuova proprietà e un <Value> tag che specifica il valore della proprietà.

Ad esempio, il codice XML seguente crea una proprietà Status per gli oggetti System.IO.DirectoryInfo . Il valore della proprietà Status è sempre Success.

<Type>
  <Name>System.IO.DirectoryInfo</Name>
  <Members>
    <NoteProperty>
      <Name>Status</Name>
      <Value>Success</Value>
    </NoteProperty>
  </Members>
</Type>

Propertyset

Proprietà che accettano argomenti e restituiscono un valore.

<Properties>: raccolta delle proprietà dell'oggetto .

<Property>: proprietà dell'oggetto di base.

<PropertySet>: definisce una raccolta di proprietà dell'oggetto .

Il <PropertySet> tag deve avere un <Name> tag che specifica il nome del set di proprietà e un <ReferencedProperty> tag che specifica le proprietà. I nomi delle proprietà sono racchiusi tra <Name> tag.

In Types.ps1xmli <PropertySet> tag vengono usati per definire set di proprietà per la visualizzazione predefinita di un oggetto . È possibile identificare le visualizzazioni predefinite in base al valore PsStandardMembers nel <Name> tag di un <MemberSet> tag.

Ad esempio, il codice XML seguente crea un oggetto PropertySet denominato DefaultDisplayPropertySet con tre ReferencedProperties.

<Type>
  <Name>System.ServiceProcess.ServiceController</Name>
  <Members>
    <MemberSet>
      <Name>PSStandardMembers</Name>
      <Members>
        <PropertySet>
          <Name>DefaultDisplayPropertySet</Name>
          <ReferencedProperties>
            <Name>Status</Name>
            <Name>Name</Name>
            <Name>DisplayName</Name>
          </ReferencedProperties>
        </PropertySet>
      </Members>
    </MemberSet>
  </Members>
</Type>

ScriptMethod

Definisce un metodo il cui valore è l'output di uno script.

Il <ScriptMethod> tag deve avere un <Name> tag che specifica il nome del nuovo metodo e un <Script> tag che racchiude il blocco di script che restituisce il risultato del metodo.

Ad esempio, i ConvertToDateTime metodi e ConvertFromDateTime degli oggetti di gestione (System.System.Management.ManagementObject) sono metodi script che usano i ToDateTime metodi statici e ToDmtfDateTime della System.Management.ManagementDateTimeConverter classe .

<Type>
 <Name>System.Management.ManagementObject</Name>
 <Members>
 <ScriptMethod>
   <Name>ConvertToDateTime</Name>
   <Script>
   [System.Management.ManagementDateTimeConverter]::ToDateTime($args[0])
   </Script>
 </ScriptMethod>
 <ScriptMethod>
   <Name>ConvertFromDateTime</Name>
   <Script>
   [System.Management.ManagementDateTimeConverter]::ToDmtfDateTime($args[0])
   </Script>
 </ScriptMethod>
 </Members>
</Type>

ScriptProperty

Definisce una proprietà il cui valore è l'output di uno script.

Il <ScriptProperty> tag deve avere un <Name> tag che specifica il nome della nuova proprietà e un <GetScriptBlock> tag che racchiude il blocco di script che restituisce il valore della proprietà.

Ad esempio, la proprietà VersionInfo dell'oggetto System.IO.FileInfo è una proprietà script risultante dall'utilizzo della proprietà FullName del metodo statico GetVersionInfo degli oggetti System.Diagnostics.FileVersionInfo .

<Type>
  <Name>System.IO.FileInfo</Name>
  <Members>
    <ScriptProperty>
      <Name>VersionInfo</Name>
      <GetScriptBlock>
      [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName)
      </GetScriptBlock>
    </ScriptProperty>
  </Members>
</Type>

Per altre informazioni, vedere Windows PowerShell Software Development Kit (SDK).

Update-TypeData

Per caricare i Types.ps1xml file in una sessione di PowerShell, eseguire il Update-TypeData cmdlet . Se si vuole che i tipi nel file hanno la precedenza sui tipi nel file predefinito Types.ps1xml , aggiungere il parametro PrependData di Update-TypeData. Update-TypeData influisce solo sulla sessione corrente. Per apportare la modifica a tutte le sessioni future, esportare la sessione o aggiungere il Update-TypeData comando al profilo di PowerShell.

Le eccezioni che si verificano nelle proprietà o dall'aggiunta di proprietà a un Update-TypeData comando non segnalano errori a StdErr. Ciò serve a sopprimere le eccezioni che si verificherebbero in molti dei tipi più comuni durante la formattazione e l'output. Se si ottengono proprietà .NET, è possibile aggirare l'eliminazione delle eccezioni usando invece la sintassi del metodo, come illustrato nell'esempio seguente:

"hello".get_Length()

Si noti che la sintassi del metodo può essere usata solo con le proprietà .NET. Le proprietà aggiunte eseguendo il cmdlet non possono usare la sintassi del Update-TypeData metodo.

Firma di un file Types.ps1xml

Per proteggere gli utenti del Types.ps1xml file, è possibile firmare il file usando una firma digitale. Per altre informazioni, vedere about_Signing.