about_Format.ps1xml

Article
04/13/2023

Description courte

Les Format.ps1xml fichiers de PowerShell définissent l’affichage par défaut des objets dans la console PowerShell. Vous pouvez créer vos propres Format.ps1xml fichiers pour modifier l’affichage des objets ou définir les affichages par défaut pour les nouveaux types d’objets que vous créez dans PowerShell.

Description longue

Les Format.ps1xml fichiers dans PowerShell définissent l’affichage par défaut des objets dans PowerShell. Vous pouvez créer vos propres Format.ps1xml fichiers pour modifier l’affichage des objets ou définir les affichages par défaut pour les nouveaux types d’objets que vous créez dans PowerShell.

Lorsque PowerShell affiche un objet, il utilise les données dans les fichiers de mise en forme structurée pour déterminer l’affichage par défaut de l’objet. Les données des fichiers de mise en forme déterminent si l’objet est rendu dans une table ou dans une liste, et détermine les propriétés affichées par défaut.

La mise en forme affecte l’affichage uniquement. Elle n’affecte pas les propriétés d’objet transmises au pipeline ou la façon dont elles sont passées. Format.ps1xml les fichiers ne peuvent pas être utilisés pour personnaliser le format de sortie des tables de hachage.

PowerShell inclut sept fichiers de mise en forme. Ces fichiers se trouvent dans le répertoire d’installation ($PSHOME). Chaque fichier définit l’affichage d’un groupe d’objets Microsoft .NET Framework :

Certificate.Format.ps1xml

Objets dans le magasin de certificats, tels que les certificats X.509 et les magasins de certificats.
DotNetTypes.Format.ps1xml

Autres types .NET Framework, tels que CultureInfo, FileVersionInfo et EventLogEntry.
FileSystem.Format.ps1xml

Objets de système de fichiers, tels que les fichiers et les répertoires.
Help.Format.ps1xml

Aidez les vues, telles que des vues détaillées et complètes, des paramètres et des exemples.
PowerShellCore.Format.ps1xml

Objets générés par les applets de commande principales PowerShell, telles que Get-Member et Get-History.
PowerShellTrace.Format.ps1xml

Objets de trace, tels que ceux générés par l’applet de Trace-Command commande.
Registry.Format.ps1xml

Objets de Registre, tels que les clés et les entrées.

Un fichier de mise en forme peut définir quatre vues différentes de chaque objet :

Table
List
Paysage
Personnalisée

Par exemple, lorsque la sortie d’une Get-ChildItem commande est redirigée vers une Format-List commande, Format-List utilise l’affichage dans le FileSystem.Format.ps1xml fichier pour déterminer comment afficher les objets de fichier et de dossier sous forme de liste.

Lorsqu’un fichier de mise en forme inclut plusieurs vues d’un objet, PowerShell applique la première vue qu’il trouve.

Dans un Format.ps1xml fichier, une vue est définie par un ensemble de balises XML qui décrivent le nom de la vue, le type d’objet auquel il peut être appliqué, les en-têtes de colonne et les propriétés affichées dans le corps de la vue. Le format dans les Format.ps1xml fichiers est appliqué juste avant que les données ne sont présentées à l’utilisateur.

Création de fichiers Format.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. Pour modifier le format d’affichage d’une vue d’objet existante ou pour ajouter des vues pour de nouveaux objets, créez vos propres Format.ps1xml fichiers, puis ajoutez-les à votre session PowerShell.

Pour créer un fichier, copiez un fichier existant Format.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.

Pour modifier la mise en forme d’une vue active, recherchez l’affichage dans le fichier de mise en forme, puis utilisez les balises pour modifier l’affichage. Pour créer une vue pour un nouveau type d’objet, créez une vue ou utilisez une vue existante en tant que modèle. Les balises sont décrites dans la section suivante. Vous pouvez ensuite supprimer toutes les autres vues du fichier afin que les modifications soient évidentes pour toute personne examinant le fichier.

Après avoir enregistré les modifications, utilisez l’applet Update-FormatData de commande pour ajouter le nouveau fichier à votre session PowerShell. Si vous souhaitez que votre vue soit prioritaire sur une vue définie dans les fichiers intégrés, utilisez le paramètre PrependPath . Update-FormatData affecte uniquement la session active. Pour apporter la modification à toutes les sessions futures, ajoutez la Update-FormatData commande à votre profil PowerShell.

Exemple : Ajout de données de calendrier à des objets de culture

Cet exemple montre comment modifier la mise en forme des objets de culture System.Globalization.CultureInfo générés par l’applet Get-Culture de commande dans la session PowerShell actuelle. Les commandes de l’exemple ajoutent la propriété Calendar à l’affichage de table par défaut des objets de culture.

La première étape consiste à rechercher le Format.ps1xml fichier qui contient l’affichage actuel des objets de culture. La commande suivante Select-String recherche le fichier :

$Parms = @{
  Path = "$PSHOME\*Format.ps1xml"
  Pattern = "System.Globalization.CultureInfo"
}

Select-String @Parms

C:\Windows\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:113:
     <Name>System.Globalization.CultureInfo</Name>
C:\Windows\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:115:
<TypeName>System.Globalization.CultureInfo</TypeName>

Cette commande indique que la définition se trouve dans le DotNetTypes.Format.ps1xml fichier.

La commande suivante copie le contenu du fichier dans un nouveau fichier. MyDotNetTypes.Format.ps1xml

Copy-Item $PSHome\DotNetTypes.format.ps1xml MyDotNetTypes.Format.ps1xml

Ouvrez le MyDotNetTypes.Format.ps1xml fichier dans n’importe quel éditeur xml ou texte, tel que Visual Studio Code. Recherchez la section de l’objet System.Globalization.CultureInfo . Le code XML suivant définit les vues de l’objet CultureInfo . L’objet n’a qu’une vue TableControl .

<View>
  <Name>System.Globalization.CultureInfo</Name>
  <ViewSelectedBy>
    <TypeName>Deserialized.System.Globalization.CultureInfo</TypeName>
    <TypeName>System.Globalization.CultureInfo</TypeName>
  </ViewSelectedBy>
  <TableControl>
    <TableHeaders>
      <TableColumnHeader>
        <Width>16</Width>
      </TableColumnHeader>
      <TableColumnHeader>
        <Width>16</Width>
      </TableColumnHeader>
    </TableHeaders>
    <TableRowEntries>
      <TableRowEntry>
        <TableColumnItems>
          <TableColumnItem>
            <PropertyName>LCID</PropertyName>
          </TableColumnItem>
          <TableColumnItem>
            <PropertyName>Name</PropertyName>
          </TableColumnItem>
          <TableColumnItem>
            <PropertyName>DisplayName</PropertyName>
          </TableColumnItem>
        </TableColumnItems>
      </TableRowEntry>
    </TableRowEntries>
  </TableControl>
</View>

Supprimez le reste du fichier, à l’exception de l’ouverture <?xml>, <Configuration>des balises et <ViewDefinitions> des balises et de la fermeture <ViewDefinitions> et <Configuration> des balises. S’il existe une signature numérique, supprimez-la de votre fichier personnalisé Format.ps1xml.

Le MyDotNetTypes.Format.ps1xml fichier doit maintenant ressembler à l’exemple suivant :

<?xml version="1.0" encoding="utf-8" ?>
<Configuration>
<ViewDefinitions>
<View>
  <Name>System.Globalization.CultureInfo</Name>
  <ViewSelectedBy>
    <TypeName>Deserialized.System.Globalization.CultureInfo</TypeName>
    <TypeName>System.Globalization.CultureInfo</TypeName>
  </ViewSelectedBy>
  <TableControl>
    <TableHeaders>
      <TableColumnHeader>
        <Width>16</Width>
      </TableColumnHeader>
      <TableColumnHeader>
        <Width>16</Width>
      </TableColumnHeader>
      <TableColumnHeader/>
    </TableHeaders>
    <TableRowEntries>
      <TableRowEntry>
        <TableColumnItems>
          <TableColumnItem>
            <PropertyName>LCID</PropertyName>
          </TableColumnItem>
          <TableColumnItem>
            <PropertyName>Name</PropertyName>
          </TableColumnItem>
          <TableColumnItem>
            <PropertyName>DisplayName</PropertyName>
          </TableColumnItem>
        </TableColumnItems>
      </TableRowEntry>
    </TableRowEntries>
  </TableControl>
</View>
</ViewDefinitions>
</Configuration>

Créez une colonne pour la propriété Calendar en ajoutant un nouvel ensemble de <TableColumnHeader> balises. La valeur de la propriété Calendar peut être longue. Spécifiez donc une valeur de 45 caractères en tant que <Width>.

<TableHeaders>
  <TableColumnHeader>
    <Width>16</Width>
  </TableColumnHeader>
  <TableColumnHeader>
    <Width>16</Width>
  </TableColumnHeader>
  <TableColumnHeader>
    <Width>45</Width>
  </TableColumnHeader>
  <TableColumnHeader/>
</TableHeaders>

Ajoutez un nouvel élément de colonne pour Calendar dans les lignes du tableau à l’aide des balises et <PropertyName des <TableColumnItem> balises :

<TableRowEntries>
  <TableRowEntry>
    <TableColumnItems>
      <TableColumnItem>
        <PropertyName>LCID</PropertyName>
      </TableColumnItem>
      <TableColumnItem>
        <PropertyName>Name</PropertyName>
      </TableColumnItem>
      <TableColumnItem>
        <PropertyName>Calendar</PropertyName>
      </TableColumnItem>
      <TableColumnItem>
        <PropertyName>DisplayName</PropertyName>
      </TableColumnItem>
    </TableColumnItems>
  </TableRowEntry>
</TableRowEntries>

Enregistrez le fichier et fermez-le. Permet Update-FormatData d’ajouter le nouveau fichier de format à la session PowerShell actuelle.

Cet exemple utilise le paramètre PrependPath pour placer le nouveau fichier dans un ordre de priorité supérieur à celui du fichier d’origine. Pour plus d’informations, consultez Update-FormatData.

Update-FormatData -PrependPath $PSHOME\MyDotNetTypes.Format.ps1xml

Pour tester la modification, tapez Get-Culture et passez en revue la sortie qui inclut la propriété Calendar .

Get-Culture

LCID Name  Calendar                               DisplayName
---- ----  --------                               -----------
1033 en-US System.Globalization.GregorianCalendar English (United States)

Xml dans les fichiers Format.ps1xml

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

La section ViewDefinitions de chaque Format.ps1xml fichier contient les <View> balises qui définissent chaque vue. Une balise classique <View> inclut les balises suivantes :

<Name> identifie le nom de la vue.
<ViewSelectedBy> spécifie le type d’objet ou les types auxquels l’affichage s’applique.
<GroupBy> spécifie la façon dont les éléments de la vue seront combinés dans des groupes.
<TableControl>, <ListControl>, <WideControl>et <CustomControl> contiennent les balises qui spécifient la façon dont chaque élément sera affiché.

Balise ViewSelectedBy

La <ViewSelectedBy> balise peut contenir une <TypeName> balise pour chaque type d’objet auquel l’affichage s’applique. Il peut également contenir une <SelectionSetName> balise qui fait référence à un jeu de sélection défini ailleurs à l’aide d’une <SelectionSet> balise.

Balise GroupBy

La <GroupBy> balise contient une <PropertyName> balise qui spécifie la propriété d’objet par laquelle les éléments doivent être regroupés. Il contient également une <Label> balise qui spécifie une chaîne à utiliser comme étiquette pour chaque groupe ou une <CustomControlName> balise qui fait référence à un contrôle personnalisé défini ailleurs à l’aide d’une <Control> balise. La <Control> balise contient une <Name> balise et une <CustomControl> balise.

TableControlTag

La <TableControl> balise contient généralement et <TableRowEntries> étiquettes <TableHeaders> qui définissent la mise en forme des têtes et des lignes du tableau. La <TableHeaders> balise contient <TableColumnHeader> généralement des balises qui contiennent <Label>, <Width>et <Alignment> des balises. La <TableRowEntries> balise contient des <TableRowEntry> balises pour chaque ligne du tableau. La <TableRowEntry> balise contient une balise qui contient une <TableColumnItem><TableColumnItems> balise pour chaque colonne de la ligne. En règle générale, la <TableColumnItem> balise contient une <PropertyName> balise qui identifie la propriété d’objet à afficher à l’emplacement défini, ou une <ScriptBlock> balise qui contient du code de script qui calcule un résultat à afficher à l’emplacement.

Remarque

Les blocs de script peuvent également être utilisés ailleurs dans des emplacements où les résultats calculés peuvent être utiles.

La <TableColumnItem> balise peut également contenir une <FormatString> balise qui spécifie la façon dont la propriété ou les résultats calculés seront affichés.

Balise ListControl

La <ListControl> balise contient généralement une <ListEntries> balise. La <ListEntries> balise contient une <ListEntry> balise. La <ListEntry> balise contient une <ListItems> balise. La <ListItems> balise contient <ListItem> des balises, qui contiennent des <PropertyName> balises. Les <PropertyName> balises spécifient la propriété d’objet à afficher à l’emplacement spécifié dans la liste. Si la sélection d’affichage est définie à l’aide d’un jeu de sélection, les <ListControl><ListEntry> balises peuvent également contenir une <EntrySelectedBy> balise contenant une ou plusieurs <TypeName> balises. Ces <TypeName> balises spécifient le type d’objet que la <ListControl> balise est destinée à afficher.

Balise WideControl

La <WideControl> balise contient généralement une <WideEntries> balise. La <WideEntries> balise contient une ou plusieurs <WideEntry> balises. Une <WideEntry> balise contient une <WideItem> balise.

Une <WideItem> balise doit inclure une <PropertyName> balise ou une <ScriptBlock> balise. Une <PropertyName> balise spécifie la propriété à afficher à l’emplacement spécifié dans l’affichage. Une <ScriptBlock> balise spécifie un script à évaluer et à afficher à l’emplacement spécifié dans l’affichage.

Une <WideItem> balise peut contenir une <FormatString> balise qui spécifie comment afficher la propriété.

Balise CustomControl

La <CustomControl> balise vous permet d’utiliser un bloc de script pour définir un format. Une <CustomControl> balise contient généralement une <CustomEntries> balise qui contient plusieurs <CustomEntry> balises. Chaque <CustomEntry> balise contient une <CustomItem> balise qui peut contenir une variété d’étiquettes qui spécifient le contenu et la mise en forme de l’emplacement spécifié dans l’affichage, notamment <Text>, , <Indentation><ExpressionBinding>et <NewLine> les balises.

Affichages par défaut dans Types.ps1xml

Les affichages par défaut de certains types d’objets de base sont définis dans le Types.ps1xml fichier du $PSHOME répertoire. Les nœuds sont nommés PsStandardMembers et les sous-nœuds utilisent l’une des balises suivantes :

<DefaultDisplayProperty>
<DefaultDisplayPropertySet>
<DefaultKeyPropertySet>

Pour plus d’informations, consultez about_Types.ps1xml.

Utilisation du fichier Format.ps1xml de suivi

Pour détecter les erreurs dans le chargement ou l’application de fichiers, utilisez l’applet de Format.ps1xml commande avec l’un des composants de format suivants comme valeur du paramètre Name :Trace-Command

FormatFileLoading
FormatViewBinding

Pour plus d’informations, consultez Trace-Command et Get-TraceSource.

Signature d’un fichier Format.ps1xml

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

Exemple DE CODE XML pour une vue personnalisée Format-Table

L’exemple suivant crée une Format-Table vue personnalisée pour les objets System.IO.DirectoryInfo et System.IO.FileInfo créés par Get-ChildItem. La vue personnalisée est nommée mygciview et ajoute la colonne CreationTime à la table.

La vue personnalisée est créée à partir d’une version modifiée du FileSystem.Format.ps1xml fichier stocké dans $PSHOME PowerShell 5.1.

Une fois votre fichier personnalisé .ps1xml enregistré, utilisez Update-FormatData cette option pour inclure la vue dans une session PowerShell. Pour cet exemple, l’affichage personnalisé doit utiliser le format de tableau, sinon, Format-Table échoue.

Utilisez Format-Table le paramètre View pour spécifier le nom de la vue personnalisée et mettre en forme la sortie de la table. Pour obtenir un exemple de l’exécution de la commande, consultez Format-Table.

$Parms = @{
  Path = "$PSHOME\*Format.ps1xml"
  Pattern = "System.IO.DirectoryInfo"
}
Select-String @Parms
Copy-Item $PSHome\FileSystem.format.ps1xml .\MyFileSystem.Format.ps1xml
Update-FormatData -PrependPath $PSHOME\Format\MyFileSystem.Format.ps1xml