about_Format.ps1xml

Article
05/09/2024

Description courte

À compter de PowerShell 6, les vues par défaut pour les objets sont définies dans le code source PowerShell.

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

Description longue

À compter de PowerShell 6, les vues par défaut sont définies dans le code source PowerShell. Les Format.ps1xml fichiers de PowerShell 5.1 et versions antérieures n’existent pas dans PowerShell 6 et versions ultérieures.

Le code source PowerShell définit 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 des 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 dans les fichiers de mise en forme déterminent si l’objet est affiché dans une table ou dans une liste, et déterminent les propriétés affichées par défaut.

La mise en forme affecte uniquement l’affichage. Cela n’affecte pas les propriétés d’objet qui sont transmises dans le 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.

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

Table de charge de travail
Liste
Large
Custom

Par exemple, lorsque la sortie d’une Get-ChildItem commande est redirigée vers une Format-List commande, Format-List utilise l’affichage de liste défini dans le code source pour déterminer comment afficher les objets fichier et 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 fichier personnalisé Format.ps1xml , une vue est définie par un ensemble de balises XML qui décrivent le nom de la vue, le type d’objet auquel elle peut être appliquée, 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

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 Format.ps1xml fichier afin de définir une vue personnalisée, utilisez les applets de commande Get-FormatData et Export-FormatData . Utilisez un éditeur de texte pour modifier le fichier. Le fichier peut être enregistré dans n’importe quel répertoire auquel PowerShell peut accéder, tel qu’un sous-répertoire de $HOME.

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 comme 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 Update-FormatData 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 : Ajouter des 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 de Get-Culture commande dans la session PowerShell actuelle. Les commandes de l’exemple ajoutent la propriété Calendar à l’affichage table par défaut des objets de culture.

Pour commencer, récupérez les données de format à partir du fichier de code source et créez un Format.ps1xml fichier qui contient la vue actuelle des objets de culture.

Get-FormatData -TypeName System.Globalization.CultureInfo |
  Export-FormatData -Path $HOME\Format\CultureInfo.Format.ps1xml

Ouvrez le CultureInfo.Format.ps1xml fichier dans n’importe quel éditeur XML ou de texte, tel que Visual Studio Code. Le code XML suivant définit les vues de l’objet CultureInfo .

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

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <ViewDefinitions>
    <View>
      <Name>System.Globalization.CultureInfo</Name>
      <ViewSelectedBy>
        <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>

Create une nouvelle 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 comme <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 <TableColumnItem> balises et <PropertyName :

<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 et fermez le fichier. Utilisez Update-FormatData pour ajouter le nouveau fichier de format à la session PowerShell active.

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 $HOME\Format\CultureInfo.Format.ps1xml

Pour tester la modification, tapez Get-Culture et examinez 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> comprend les balises suivantes :

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

Balise ViewSelectedBy

La <ViewSelectedBy> balise peut contenir une <TypeName> balise pour chaque type d’objet auquel la vue 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 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 <TableHeaders> généralement des balises et <TableRowEntries> qui définissent la mise en forme des lignes et des têtes du tableau. La <TableHeaders> balise contient <TableColumnHeader> généralement des balises qui contiennent des <Label>balises , <Width>et <Alignment> . La <TableRowEntries> balise contient <TableRowEntry> des balises pour chaque ligne de la table. La <TableRowEntry> balise contient une <TableColumnItems> balise qui contient une <TableColumnItem> balise pour chaque colonne de la ligne. En règle générale, la <TableColumnItem> balise contient soit une <PropertyName> balise qui identifie la propriété d’objet à afficher à l’emplacement défini, soit une balise qui contient du <ScriptBlock> code de script qui calcule un résultat qui doit être affiché à l’emplacement.

Notes

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 comment 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 <PropertyName> des 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> balises et <ListEntry> peuvent également contenir une <EntrySelectedBy> balise qui contient 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 la vue. Une <ScriptBlock> balise spécifie un script à évaluer et à afficher à l’emplacement spécifié dans la vue.

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é de balises qui spécifient le contenu et la mise en forme de l’emplacement spécifié dans la vue, y compris <Text>les balises , <Indentation>, <ExpressionBinding>et <NewLine> .

Utilisation du fichier Tracing Format.ps1xml

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

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 XML 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.

Pour créer l’affichage personnalisé, utilisez les Get-FormatData applets de commande et Export-FormatData pour générer un .ps1xml fichier. Ensuite, modifiez votre .ps1xml fichier pour créer le code de votre vue personnalisée. Le .ps1xml fichier peut être stocké dans n’importe quel répertoire auquel PowerShell peut accéder. Par exemple, un sous-répertoire de $HOME.

Une fois le .ps1xml fichier créé, utilisez l’applet Update-FormatData de commande pour inclure la vue dans la session PowerShell actuelle. Vous pouvez également ajouter la commande de mise à jour à votre profil PowerShell si vous avez besoin de l’affichage disponible dans toutes les sessions PowerShell.

Pour cet exemple, l’affichage personnalisé doit utiliser le format de tableau, sinon, Format-Table échoue.

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