Partager via

about_Format.ps1xml

Brève description

À 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 fichiers Format.ps1xml 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

À compter de PowerShell 6, les vues par défaut sont définies dans le code source PowerShell. Les fichiers Format.ps1xml 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 fichiers Format.ps1xml 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 fichiers ne peuvent pas être utilisés pour personnaliser le format de sortie des tables de hachage.

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

  • Table
  • Liste
  • Paysage
  • Coutume

Par exemple, lorsque la sortie d’une commande Get-ChildItem est redirigée vers une commande Format-List, Format-List utilise l’affichage de liste défini dans le code source 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 fichier de Format.ps1xml personnalisé, 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 des fichiers Format.ps1xml est appliqué juste avant que les données ne soient 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 fichiers Format.ps1xml, puis ajoutez-les à votre session PowerShell.

Pour créer un fichier Format.ps1xml pour 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 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 le 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 ultérieures, ajoutez la commande Update-FormatData à 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ée par l’applet de commande Get-Culture dans la session PowerShell actuelle. Les commandes de l’exemple ajoutent la propriété Calendar à l’affichage de la table par défaut des objets culturels.

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

New-Item -Path $HOME\Format -ItemType Directory -Force

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

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

Le fichier CultureInfo.Format.ps1xml 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>

Créez une colonne pour la propriété Calendar en ajoutant un nouvel ensemble de balises <TableColumnHeader>. 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 Calendrier dans les lignes du tableau à l’aide des balises <TableColumnItem> 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 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, veuillez consulter la section Update-FormatData.

Update-FormatData -PrependPath $HOME\Format\CultureInfo.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

Vous trouverez la définition complète du schéma dans format.xsd dans le référentiel de code source PowerShell sur GitHub.

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

  • <Name> identifie le nom de l’affichage.
  • <ViewSelectedBy> spécifie le type d’objet ou les types auxquels la vue 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 balise <ViewSelectedBy> peut contenir une balise <TypeName> pour chaque type d’objet auquel l’affichage s’applique. Il peut également contenir une balise <SelectionSetName> qui fait référence à un jeu de sélection défini ailleurs à l’aide d’une balise de <SelectionSet>.

Balise GroupBy

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

TableControlTag

La balise <TableControl> contient généralement des balises <TableHeaders> et <TableRowEntries> qui définissent la mise en forme des têtes et lignes du tableau. La balise <TableHeaders> contient généralement des balises <TableColumnHeader> qui contiennent des balises <Label>, <Width>et <Alignment>. La balise <TableRowEntries> contient des balises <TableRowEntry> pour chaque ligne du tableau. La balise <TableRowEntry> contient une balise <TableColumnItems> qui contient une balise <TableColumnItem> pour chaque colonne de la ligne. En règle générale, la balise <TableColumnItem> contient une balise <PropertyName> qui identifie la propriété d’objet à afficher à l’emplacement défini, ou une balise de <ScriptBlock> 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 balise <TableColumnItem> peut également contenir une balise de <FormatString> qui spécifie la façon dont la propriété ou les résultats calculés seront affichés.

Balise ListControl

La balise <ListControl> contient généralement une balise de <ListEntries>. La balise <ListEntries> contient une balise de <ListEntry>. La balise <ListEntry> contient une balise de <ListItems>. La balise <ListItems> contient des balises <ListItem>, qui contiennent des balises <PropertyName>. Les balises <PropertyName> 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 balises <ListControl> et <ListEntry> peuvent également contenir une balise <EntrySelectedBy> qui contient une ou plusieurs balises <TypeName>. Ces balises <TypeName> spécifient le type d’objet que la balise <ListControl> est destinée à afficher.

Balise WideControl

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

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

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

Balise CustomControl

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

Utilisation du fichier Format.ps1xml de suivi

Pour détecter les erreurs dans le chargement ou l’application de fichiers Format.ps1xml, utilisez l’applet de commande Trace-Command 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 fichier Format.ps1xml, 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 vue personnalisée Format-Table 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 applets de commande Get-FormatData et Export-FormatData pour générer un fichier .ps1xml. Ensuite, modifiez votre fichier .ps1xml pour créer le code de votre vue personnalisée. Le fichier .ps1xml 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 fichier .ps1xml créé, utilisez l’applet de commande Update-FormatData pour inclure la vue dans la session PowerShell active. Vous pouvez également ajouter la commande de mise à jour à votre profil PowerShell si vous avez besoin de la vue 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 de l’exécution de la commande, consultez Format-Table.

Remarque

Bien que vous puissiez obtenir le code XML de mise en forme à partir du code source pour créer une vue personnalisée, un développement supplémentaire peut être nécessaire pour obtenir le résultat souhaité.

Dans la commande Get-FormatData suivante, il existe une alternative au paramètre PowerShellVersion pour vous assurer que toutes les informations de mise en forme locales sont retournées. Utilisez -PowerShellVersion $PSVersionTable.PSVersion plutôt qu’une version Spécifique de PowerShell.

Get-FormatData -PowerShellVersion 5.1 -TypeName System.IO.DirectoryInfo |
   Export-FormatData -LiteralPath $HOME\Format\MyGciView.Format.ps1xml

Update-FormatData -AppendPath $HOME\Format\MyGciView.Format.ps1xml

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <ViewDefinitions>
    <View>
      <Name>MyGciView</Name>
      <ViewSelectedBy>
        <TypeName>System.IO.DirectoryInfo</TypeName>
        <TypeName>System.IO.FileInfo</TypeName>
      </ViewSelectedBy>
      <GroupBy>
        <PropertyName>PSParentPath</PropertyName>
      </GroupBy>
      <TableControl>
        <TableHeaders>
          <TableColumnHeader>
            <Label>Mode</Label>
            <Width>7</Width>
            <Alignment>Left</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>LastWriteTime</Label>
            <Width>26</Width>
            <Alignment>Right</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>CreationTime</Label>
            <Width>26</Width>
            <Alignment>Right</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>Length</Label>
            <Width>14</Width>
            <Alignment>Right</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>Name</Label>
            <Alignment>Left</Alignment>
          </TableColumnHeader>
        </TableHeaders>
        <TableRowEntries>
          <TableRowEntry>
            <Wrap />
            <TableColumnItems>
              <TableColumnItem>
                <PropertyName>ModeWithoutHardLink</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>LastWriteTime</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>CreationTime</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>Length</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>Name</PropertyName>
              </TableColumnItem>
            </TableColumnItems>
          </TableRowEntry>
        </TableRowEntries>
      </TableControl>
    </View>
  </ViewDefinitions>
</Configuration>

Voir aussi

  • Last updated on