about_Types.ps1xml

Article
08/07/2024

Description courte

Explique comment utiliser Types.ps1xml des fichiers pour étendre les types d’objets utilisés dans PowerShell.

Description longue

Les données de type étendues définissent des propriétés et des méthodes supplémentaires (« membres ») des types d’objets dans PowerShell. Il existe deux techniques pour ajouter des données de type étendu à une session PowerShell.

Types.ps1xml fichier : fichier XML qui définit les données de type étendu.
Update-TypeData: applet de commande qui recharge les fichiers et définit des données étendues Types.ps1xml pour les types dans la session active.

Cette rubrique décrit les Types.ps1xml fichiers. Pour plus d’informations sur l’utilisation de l’applet Update-TypeData de commande pour ajouter des données de type étendue dynamiques à la session active, consultez Update-TypeData.

À propos des données de type étendu

Les données de type étendues définissent des propriétés et des méthodes supplémentaires (« membres ») des types d’objets dans PowerShell. Vous pouvez étendre n’importe quel type pris en charge par PowerShell et utiliser les propriétés et méthodes ajoutées de la même façon que les propriétés définies sur les types d’objets.

Par exemple, PowerShell ajoute une propriété DateTime à tous les System.DateTime objets, tels que ceux retournés par l’applet Get-Date de commande.

(Get-Date).DateTime

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

Vous ne trouverez pas la propriété DateTime dans la description de la structure System.DateTime , car PowerShell ajoute la propriété et elle est visible uniquement dans PowerShell.

PowerShell définit en interne un ensemble par défaut de types étendus. Ces informations de type sont chargées dans chaque session PowerShell au démarrage. La propriété DateTime fait partie de cet ensemble par défaut. Avant PowerShell 6, les définitions de type ont été stockées dans Types.ps1xml le répertoire d’installation de PowerShell ($PSHOME).

Ajout de données de type étendu à PowerShell

Il existe trois sources de données de type étendu dans les sessions PowerShell.

Les données de type étendu sont définies par PowerShell et chargées automatiquement dans chaque session PowerShell. À compter de PowerShell 6, ces informations sont compilées dans PowerShell et ne sont plus livrées dans un Types.ps1xml fichier.
Les Types.ps1xml fichiers que les modules exportent sont chargés lorsque le module est importé dans la session active.
Les données de type étendues définies à l’aide de l’applet Update-TypeData de commande sont ajoutées uniquement à la session active. Il n’est pas enregistré dans un fichier.

Dans la session, les données de type étendu des trois sources sont appliquées aux objets de la même façon et sont disponibles sur tous les objets des types spécifiés.

Applets de commande TypeData

Les applets de commande suivantes sont incluses dans le module Microsoft.PowerShell.Utility dans PowerShell 3.0 et versions ultérieures.

Get-TypeData: obtient les données de type étendu dans la session active.
Update-TypeData: recharge les Types.ps1xml fichiers. Ajoute des données de type étendu à la session active.
Remove-TypeData: supprime les données de type étendu de la session active.

Pour plus d’informations sur ces applets de commande, consultez la rubrique d’aide pour chaque applet de commande.

Fichiers Types.ps1xml intégrés

Les Types.ps1xml fichiers du $PSHOME répertoire sont ajoutés automatiquement à chaque session.

Le Types.ps1xml fichier du répertoire d’installation de PowerShell ($PSHOME) est un fichier texte xml qui vous permet d’ajouter des propriétés et des méthodes aux objets utilisés dans PowerShell. PowerShell a des fichiers intégrés Types.ps1xml qui ajoutent plusieurs éléments aux types .NET, mais vous pouvez créer des fichiers supplémentaires Types.ps1xml pour étendre davantage les types.

Par exemple, par défaut, les objets de tableau (System.Array) ont une propriété Length qui répertorie le nombre d’objets dans le tableau. Toutefois, étant donné que le nom Length ne décrit pas clairement la propriété, PowerShell ajoute une propriété alias nommée Count qui affiche la même valeur. Le code XML suivant ajoute la propriété Count au System.Array type.

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

Pour obtenir le nouvel AliasProperty, utilisez une Get-Member commande sur n’importe quel tableau, comme illustré dans l’exemple suivant.

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

La commande retourne les résultats suivants.

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)
# ...

Par conséquent, vous pouvez utiliser la propriété Count ou la propriété Length des tableaux dans PowerShell. Par exemple :

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

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

Création de fichiers Types.ps1xml

Les .ps1xml fichiers installés avec PowerShell sont signés numériquement pour empêcher la falsification, car la mise en forme peut inclure des blocs de script. Par conséquent, pour ajouter une propriété ou une méthode à un type .NET, créez vos propres Types.ps1xml fichiers, puis ajoutez-les à votre session PowerShell.

Pour créer un fichier, commencez par copier un fichier existant Types.ps1xml . Le nouveau fichier peut avoir n’importe quel nom, mais il doit avoir une .ps1xml extension de nom de fichier. Vous pouvez placer le nouveau fichier dans n’importe quel répertoire accessible à PowerShell, mais il est utile de placer les fichiers dans le répertoire d’installation de PowerShell ($PSHOME) ou dans un sous-répertoire du répertoire d’installation.

Lorsque vous avez enregistré le nouveau fichier, utilisez l’applet Update-TypeData de commande pour ajouter le nouveau fichier à votre session PowerShell. Si vous souhaitez que vos types soient prioritaires sur les types intégrés définis, utilisez le paramètre PrependData de l’applet Update-TypeData de commande. Update-TypeData affecte uniquement la session active. Pour apporter la modification à toutes les sessions futures, exportez la console ou ajoutez la Update-TypeData commande à votre profil PowerShell.

Types.ps1xml et Add-Member

Les Types.ps1xml fichiers ajoutent des propriétés et des méthodes à toutes les instances des objets du type .NET spécifié dans la session PowerShell affectée. Toutefois, si vous devez ajouter des propriétés ou des méthodes à une seule instance d’un objet, utilisez l’applet Add-Member de commande.

Pour plus d’informations, consultez Add-Member.

Exemple : ajout d’un membre Age à des objets FileInfo

Cet exemple montre comment ajouter une propriété Age aux objets System.IO.FileInfo . L’âge d’un fichier est la différence entre son heure de création et l’heure actuelle en jours.

Étant donné que la propriété Age est calculée à l’aide d’un bloc de script, recherchez une <ScriptProperty> balise à utiliser comme modèle pour la nouvelle propriété Age .

Enregistrez le code XML suivant dans le fichier $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>

Exécutez Update-TypeData pour ajouter le nouveau Types.ps1xml fichier à la session active. La commande utilise le paramètre PrependData pour placer le nouveau fichier dans un ordre de priorité supérieur aux définitions d’origine.

Pour plus d’informations sur Update-TypeData, consultez Update-TypeData.

Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml

Pour tester la modification, exécutez une Get-ChildItem commande pour obtenir le fichier PowerShell.exe dans le $PSHOME répertoire, puis diriger le fichier vers l’applet Format-List de commande pour répertorier toutes les propriétés du fichier. À la suite de la modification, la propriété Age apparaît dans la liste.

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

Xml dans les fichiers Types.ps1xml

La définition complète du schéma se trouve dans Types.xsd dans le référentiel de code source PowerShell sur GitHub.

La <Types> balise entoure tous les types définis dans le fichier. Il ne doit y avoir qu’une <Types> seule balise.

Chaque type .NET mentionné dans le fichier doit être représenté par une <Type> balise.

Les balises de type doivent contenir les balises suivantes :

<Name>: place le nom du type .NET concerné.

<Members>: place les balises pour les nouvelles propriétés et méthodes définies pour le type .NET.

L’une des balises membres suivantes peut se trouver à l’intérieur de la <Members> balise.

AliasProperty

Définit un nouveau nom pour une propriété existante.

La <AliasProperty> balise doit avoir une <Name> balise qui spécifie le nom de la nouvelle propriété et une <ReferencedMemberName> balise qui spécifie la propriété existante.

Par exemple, la propriété Count alias est un alias pour la propriété Length des objets de tableau.

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

CodeMethod

Fait référence à une méthode statique d’une classe .NET.

La <CodeMethod> balise doit avoir une <Name> balise qui spécifie le nom de la nouvelle méthode et une <CodeReference> balise qui spécifie le code dans lequel la méthode est définie.

Par exemple, la méthode ToString est le nom de la définition de code 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

Fait référence à une méthode statique d’une classe .NET.

La <CodeProperty> balise doit avoir une <Name> balise qui spécifie le nom de la nouvelle propriété et une <GetCodeReference> balise qui spécifie le code dans lequel la propriété est définie.

Par exemple, la propriété Mode des objets est une propriété de System.IO.DirectoryInfo code définie dans le fournisseur PowerShell FileSystem.

<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

Définit une collection de membres (propriétés et méthodes).

Les <MemberSet> balises apparaissent dans les balises primaires <Members> . Les balises doivent placer une <Name> balise entourant le nom du jeu de membres et une balise secondaire <Members> qui entourent les membres (propriétés et méthodes) dans l’ensemble. Toutes les balises qui créent une propriété (par exemple <NoteProperty> ou <ScriptProperty>) ou une méthode (par exemple <Method> ) <ScriptMethod>peuvent être membres de l’ensemble.

Dans Types.ps1xml les fichiers, la <MemberSet> balise est utilisée pour définir les vues par défaut des objets .NET dans PowerShell. Dans ce cas, le nom du jeu de membres (la valeur dans les <Name> balises) est toujours PsStandardMembers, et les noms des propriétés (la valeur de la <Name> balise) sont l’un des éléments suivants :

DefaultDisplayProperty: propriété unique d’un objet.
DefaultDisplayPropertySet: Une ou plusieurs propriétés d’un objet.
DefaultKeyPropertySet: Une ou plusieurs propriétés clés d’un objet. Une propriété clé identifie les instances de valeurs de propriété, telles que le numéro d’ID des éléments d’un historique de session.

Par exemple, le code XML suivant définit l’affichage par défaut des services (System.ServiceProcess.ServiceController objets) retournés par l’applet Get-Service de commande. Il définit un jeu de membres nommé PsStandardMembers qui se compose d’un jeu de propriétés par défaut et d’une propriété d’affichage par défaut. Il définit la propriété par défaut définie comme propriétés Status, Name et DisplayName . Elle définit la propriété d’affichage par défaut comme Name.

<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>
        <NoteProperty>
          <Name>DefaultDisplayProperty</Name>
          <Value>Name</Value>
        </NoteProperty>
      </Members>
    </MemberSet>
  </Members>
</Type>

<Method>: fait référence à une méthode native de l’objet sous-jacent.

<Methods>: collection des méthodes de l’objet.

RemarqueProperty

Définit une propriété avec une valeur statique.

La <NoteProperty> balise doit avoir une <Name> balise qui spécifie le nom de la nouvelle propriété et une <Value> balise qui spécifie la valeur de la propriété.

Par exemple, le code XML suivant crée une propriété Status pour les objets System.IO.DirectoryInfo . La valeur de la propriété Status est toujours Success.

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

PropertySet

Propriétés qui prennent des arguments et retournent une valeur.

<Properties>: collection des propriétés de l’objet.

<Property>: propriété de l’objet de base.

<PropertySet>: définit une collection de propriétés de l’objet.

La <PropertySet> balise doit avoir une <Name> balise qui spécifie le nom du jeu de propriétés et une <ReferencedProperty> balise qui spécifie les propriétés. Les noms des propriétés sont placés dans <Name> la balise.

Dans Types.ps1xml, <PropertySet> les balises sont utilisées pour définir des ensembles de propriétés pour l’affichage par défaut d’un objet. Vous pouvez identifier les affichages par défaut par la valeur PsStandardMembers dans la <Name> balise d’une <MemberSet> balise.

Par exemple, le code XML suivant crée un PropertySet nommé DefaultDisplayPropertySet avec trois 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

Définit une méthode dont la valeur est la sortie d’un script.

La <ScriptMethod> balise doit avoir une <Name> balise qui spécifie le nom de la nouvelle méthode et une <Script> balise qui entoure le bloc de script qui retourne le résultat de la méthode.

Par exemple, les ConvertToDateTime méthodes et ConvertFromDateTime les méthodes des objets de gestion (System.System.Management.ManagementObject) sont des méthodes de script qui utilisent les ToDateTime méthodes statiques de ToDmtfDateTime la 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

Définit une propriété dont la valeur est la sortie d’un script.

La <ScriptProperty> balise doit avoir une <Name> balise qui spécifie le nom de la nouvelle propriété et une <GetScriptBlock> balise qui entoure le bloc de script qui retourne la valeur de la propriété.

Par exemple, la propriété VersionInfo de l’objet System.IO.FileInfo est une propriété de script qui résulte de l’utilisation de la propriété FullName de la méthode statique GetVersionInfo des objets 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>

Pour plus d’informations, consultez le Kit de développement logiciel (SDK) Windows PowerShell.

Update-TypeData

Pour charger vos Types.ps1xml fichiers dans une session PowerShell, exécutez l’applet de Update-TypeData commande. Si vous souhaitez que les types de votre fichier soient prioritaires sur les types du fichier intégré Types.ps1xml , ajoutez le paramètre PrependData de Update-TypeData. Update-TypeData affecte uniquement la session active. Pour apporter la modification à toutes les sessions futures, exportez la session ou ajoutez la Update-TypeData commande à votre profil PowerShell.

Les exceptions qui se produisent dans les propriétés ou à partir de l’ajout de propriétés à une Update-TypeData commande ne signalent pas d’erreurs à StdErr. Cela permet de supprimer des exceptions qui se produisent dans de nombreux types courants durant la mise en forme et la sortie. Si vous obtenez des propriétés .NET, vous pouvez contourner la suppression des exceptions à l’aide de la syntaxe de méthode à la place, comme illustré dans l’exemple suivant :

"hello".get_Length()

Notez que la syntaxe de méthode ne peut être utilisée qu’avec les propriétés .NET. Les propriétés ajoutées en exécutant l’applet de commande ne peuvent pas utiliser la Update-TypeData syntaxe de méthode.

Signature d’un fichier Types.ps1xml

Pour protéger les utilisateurs de votre Types.ps1xml fichier, vous pouvez signer le fichier à l’aide d’une signature numérique. Pour plus d’informations, consultez about_Signing.

Partager via