about_Format.ps1xml

Artículo
05/25/2021
Tiempo de lectura: 9 minutos

Descripción breve

A partir de PowerShell 6, las vistas predeterminadas de los objetos se definen en el código fuente de PowerShell.

Puede crear sus propios archivos para cambiar la presentación de objetos o para definir las pantallas predeterminadas para los nuevos tipos de objeto que Format.ps1xml cree en PowerShell.

Descripción larga

A partir de PowerShell 6, las vistas predeterminadas se definen en el código fuente de PowerShell. Los archivos de PowerShell 5.1 y versiones anteriores no Format.ps1xml existen en PowerShell 6 y versiones posteriores.

El código fuente de PowerShell define la presentación predeterminada de objetos en la consola de PowerShell. Puede crear sus propios archivos para cambiar la presentación de objetos o para definir las pantallas predeterminadas para los nuevos tipos de objeto que Format.ps1xml cree en PowerShell.

Cuando PowerShell muestra un objeto, usa los datos en archivos de formato estructurado para determinar la presentación predeterminada del objeto. Los datos de los archivos de formato determinan si el objeto se representa en una tabla o en una lista, y determina qué propiedades se muestran de forma predeterminada.

El formato solo afecta a la presentación. No afecta a qué propiedades de objeto se pasan por la canalización ni a cómo se pasan. Format.ps1xml Los archivos no se pueden usar para personalizar el formato de salida de las tablas hash.

Un .ps1xml archivo de formato puede definir cuatro vistas diferentes de cada objeto:

Tabla
List
Ancho
Personalizado

Por ejemplo, cuando la salida de un comando se canalice a un comando, usa la vista de lista definida en el código fuente para determinar cómo mostrar los objetos de archivo y carpeta como una Get-ChildItem Format-List Format-List lista.

Cuando un archivo de formato incluye más de una vista de un objeto, PowerShell aplica la primera vista que encuentra.

En un archivo personalizado, una vista se define mediante un conjunto de etiquetas XML que describen el nombre de la vista, el tipo de objeto al que se puede aplicar, los encabezados de columna y las propiedades que se muestran en el cuerpo de la Format.ps1xml vista. El formato de Format.ps1xml los archivos se aplica justo antes de que los datos se presenten al usuario.

Creación de nuevos Format.ps1xml

Para cambiar el formato de presentación de una vista de objeto existente o para agregar vistas para nuevos objetos, cree sus propios archivos y, a continuación, agrégrelos a Format.ps1xml la sesión de PowerShell.

Para crear un Format.ps1xml archivo para definir una vista personalizada, use los cmdlets Get-FormatData y Export-FormatData. Use un editor de texto para editar el archivo. El archivo se puede guardar en cualquier directorio al que PowerShell pueda acceder, como un subdirectorio de $HOME .

Para cambiar el formato de una vista actual, busque la vista en el archivo de formato y, a continuación, use las etiquetas para cambiar la vista. Para crear una vista para un nuevo tipo de objeto, cree una nueva vista o use una vista existente como modelo. Las etiquetas se describen en la sección siguiente. A continuación, puede eliminar todas las demás vistas del archivo para que los cambios sean obvios para cualquier persona que examine el archivo.

Después de guardar los cambios, use Update-FormatData para agregar el nuevo archivo a la sesión de PowerShell. Si desea que la vista tenga prioridad sobre una vista definida en los archivos integrados, use el parámetro PrependPath. Update-FormatData afecta solo a la sesión actual. Para realizar el cambio en todas las sesiones futuras, agregue el Update-FormatData comando al perfil de PowerShell.

Ejemplo: Agregar datos de calendario a objetos de referencia cultural

En este ejemplo se muestra cómo cambiar el formato de los objetos de referencia cultural System.Globalization.CultureInfo generados por el Get-Culture cmdlet en la sesión actual de PowerShell. Los comandos del ejemplo agregan la propiedad Calendar a la visualización predeterminada de la vista de tabla de objetos de referencia cultural.

Para empezar, obtenga los datos de formato del archivo de código fuente y cree un archivo que Format.ps1xml contenga la vista actual de los objetos de referencia cultural.

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

Abra el CultureInfo.Format.ps1xml archivo en cualquier editor de texto o XML, como Visual Studio Code. El xml siguiente define las vistas del objeto CultureInfo.

El CultureInfo.Format.ps1xml archivo debe ser parecido al ejemplo siguiente:

<?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>

Cree una nueva columna para la propiedad Calendar agregando un nuevo conjunto de <TableColumnHeader> etiquetas. El valor de la propiedad Calendar puede ser largo, por lo que debe especificar un valor de 45 caracteres como <Width> .

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

Agregue un nuevo elemento de columna para Calendar en las filas de la tabla mediante las <TableColumnItem> <PropertyName etiquetas y :

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

Guarde y cierre el archivo. Use Update-FormatData para agregar el nuevo archivo de formato a la sesión actual de PowerShell.

En este ejemplo se usa el parámetro PrependPath para colocar el nuevo archivo en un orden de precedencia mayor que el archivo original. Para obtener más información, vea Update-FormatData.

Update-FormatData -PrependPath $HOME\Format\CultureInfo.Format.ps1xml

Para probar el cambio, escriba Get-Culture y revise la salida que incluye la propiedad Calendar.

Get-Culture

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

Xml en archivos Format.ps1xml

La definición de esquema completa se puede encontrar en Format.xsd en el repositorio de código fuente de PowerShell en GitHub.

La sección ViewDefinitions de cada Format.ps1xml archivo contiene las <View> etiquetas que definen cada vista. Una etiqueta <View> típica incluye las siguientes etiquetas:

<Name> identifica el nombre de la vista.
<ViewSelectedBy> especifica el tipo de objeto o los tipos a los que se aplica la vista.
<GroupBy> especifica cómo se combinarán los elementos de la vista en grupos.
<TableControl>, <ListControl> , y contienen las <WideControl> <CustomControl> etiquetas que especifican cómo se mostrará cada elemento.

Etiqueta ViewSelectedBy

La etiqueta puede contener una etiqueta para cada tipo de objeto al <ViewSelectedBy> que se aplica la <TypeName> vista. O bien, puede contener una etiqueta que hace referencia a un conjunto de selección que se define en otra <SelectionSetName> parte mediante una etiqueta <SelectionSet> .

Etiqueta GroupBy

La etiqueta contiene una etiqueta que especifica la propiedad de objeto por la que se van a <GroupBy> agrupar los <PropertyName> elementos. También contiene una etiqueta que especifica una cadena que se va a usar como etiqueta para cada grupo o una etiqueta que hace referencia a un control personalizado definido en otra parte mediante <Label> <CustomControlName> una <Control> etiqueta. La <Control> etiqueta contiene una etiqueta y una <Name> <CustomControl> etiqueta.

TableControlTag

La <TableControl> etiqueta normalmente contiene etiquetas y que definen el formato de las caras y filas de <TableHeaders> <TableRowEntries> la tabla. Normalmente, <TableHeaders> la etiqueta contiene <TableColumnHeader> etiquetas que contienen las <Label> <Width> etiquetas , y <Alignment> . La <TableRowEntries> etiqueta contiene <TableRowEntry> etiquetas para cada fila de la tabla. La <TableRowEntry> etiqueta contiene una etiqueta que contiene una etiqueta para cada columna de la <TableColumnItems> <TableColumnItem> fila. Normalmente, la etiqueta contiene una etiqueta que identifica la propiedad de objeto que se va a mostrar en la ubicación definida o una etiqueta que contiene código de script que calcula un resultado que se va a mostrar en la <TableColumnItem> <PropertyName> <ScriptBlock> ubicación.

Nota

Los bloques de script también se pueden usar en otras ubicaciones donde los resultados calculados pueden ser útiles.

La etiqueta también puede contener una etiqueta que especifica cómo se mostrará la <TableColumnItem> <FormatString> propiedad o los resultados calculados.

Etiqueta ListControl

La <ListControl> etiqueta normalmente contiene una <ListEntries> etiqueta. La <ListEntries> etiqueta contiene una <ListEntry> etiqueta. La <ListEntry> etiqueta contiene una <ListItems> etiqueta. La <ListItems> etiqueta contiene <ListItem> etiquetas, que contienen <PropertyName> etiquetas. Las <PropertyName> etiquetas especifican la propiedad de objeto que se va a mostrar en la ubicación especificada de la lista. Si la selección de vista se define mediante un conjunto de selección, las etiquetas y también pueden contener una etiqueta <ListControl> que contenga una o varias <ListEntry> <EntrySelectedBy> <TypeName> etiquetas. Estas <TypeName> etiquetas especifican el tipo de objeto que <ListControl> la etiqueta está diseñada para mostrar.

Etiqueta WideControl

Normalmente, <WideControl> la etiqueta contiene una etiqueta <WideEntries> . La <WideEntries> etiqueta contiene una o varias <WideEntry> etiquetas. Normalmente, una etiqueta contiene una etiqueta que especifica la propiedad que se va a <WideEntry> mostrar en la ubicación especificada de la <PropertyName> vista. La etiqueta puede contener una etiqueta que especifica cómo se va <PropertyName> <FormatString> a mostrar la propiedad.

Etiqueta CustomControl

La <CustomControl> etiqueta le permite usar un bloque de script para definir un formato. Normalmente, <CustomControl> una etiqueta contiene una etiqueta que contiene varias <CustomEntries> <CustomEntry> etiquetas. Cada etiqueta contiene una etiqueta que puede contener una variedad de etiquetas que especifican el contenido y el formato de la ubicación especificada en la vista, incluidas las etiquetas <CustomEntry> <CustomItem> , , y <Text> <Indentation> <ExpressionBinding> <NewLine> .

Seguimiento Format.ps1uso de archivos XML

Para detectar errores en la carga o aplicación de archivos, use el cmdlet con cualquiera de los siguientes componentes de formato como valor Format.ps1xml Trace-Command del parámetro Name:

FormatFileLoading
FormatViewBinding

Para obtener más información, vea Trace-Command y Get-TraceSource.

Firma de un Format.ps1xml

Para proteger a los usuarios del Format.ps1xml archivo, firme el archivo mediante una firma digital. Para obtener más información, vea about_Signing.

XML de ejemplo para una Format-Table personalizada

En el ejemplo XML siguiente se crea una vista personalizada para los objetos Format-Table System.IO.DirectoryInfo y System.IO.FileInfo creados por Get-ChildItem . La vista personalizada se denomina mygciview y agrega la columna CreationTime a la tabla.

Para crear la vista personalizada, use los Get-FormatData Export-FormatData cmdlets y para generar un .ps1xml archivo. A continuación, .ps1xml edite el archivo para crear el código de la vista personalizada. El .ps1xml archivo se puede almacenar en cualquier directorio al que PowerShell pueda acceder. Por ejemplo, un subdirectorio de $HOME .

Una vez .ps1xml creado el archivo, use el Update-FormatData cmdlet para incluir la vista en la sesión actual de PowerShell. O bien, agregue el comando update al perfil de PowerShell si necesita la vista disponible en todas las sesiones de PowerShell.

En este ejemplo, la vista personalizada debe usar el formato de tabla; de lo contrario, se produce Format-Table un error.

Use con el parámetro View para especificar el nombre de la vista Format-Table personalizada, mygciview y dar formato a la salida de la tabla con la columna CreationTime. Para obtener un ejemplo de cómo se ejecuta el comando, vea Format-Table.

Nota

Aunque puede obtener el formato XML del código fuente para crear una vista personalizada, es posible que sea necesario más desarrollo para obtener el resultado deseado.

En el comando siguiente, hay una alternativa para el parámetro PowerShellVersion para asegurarse de que se devuelve toda la información de Get-FormatData formato local. Use -PowerShellVersion $PSVersionTable.PSVersion en lugar de una versión específica de PowerShell.

Get-FormatData -PowerShellVersion 5.1 -TypeName System.IO.DirectoryInfo |
   Export-FormatData -Path ./Mygciview.Format.ps1xml
Update-FormatData -AppendPath ./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>