about_Format.ps1xml

Artículo
04/13/2023

Descripción breve

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

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

Descripción larga

A partir de PowerShell 6, las vistas predeterminadas se definen en el código fuente de PowerShell. Los Format.ps1xml archivos de PowerShell 5.1 y versiones anteriores no 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 Format.ps1xml archivos para cambiar la presentación de objetos o definir pantallas predeterminadas para los nuevos tipos de objetos que 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 o 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 Get-ChildItem comando se canaliza a un Format-List comando, Format-List usa la vista de lista definida en el código fuente para determinar cómo mostrar los objetos de archivo y carpeta como una 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 Format.ps1xml , 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 vista. El formato en Format.ps1xml los archivos se aplica justo antes de que se presenten los datos al usuario.

Crear nuevos archivos Format.ps1xml

Para cambiar el formato de presentación de una vista de objeto existente o agregar vistas para nuevos objetos, cree sus propios Format.ps1xml archivos y, a continuación, agréguelos a 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 tener acceso, 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: Adición de 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 de la vista de tabla predeterminada de los objetos de referencia cultural.

Para empezar, obtenga los datos de formato del archivo de código fuente y cree un Format.ps1xml archivo que 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 siguiente XML define las vistas del objeto CultureInfo .

El CultureInfo.Format.ps1xml archivo debe tener un aspecto similar al del 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 especifique 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> etiquetas y <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>

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 prioridad 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 típica <View> 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>, <WideControl>y <CustomControl> contienen las etiquetas que especifican cómo se mostrará cada elemento.

Etiqueta ViewSelectedBy

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

Etiqueta GroupBy

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

TableControlTag

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

Nota:

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

La <TableColumnItem> etiqueta también puede contener una <FormatString> etiqueta que especifica cómo se mostrará la 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 <ListControl> etiquetas y <ListEntry> también pueden contener una <EntrySelectedBy> etiqueta que contenga una o varias <TypeName> etiquetas. Estas <TypeName> etiquetas especifican el tipo de objeto que la <ListControl> etiqueta está pensada para mostrarse.

Etiqueta WideControl

La <WideControl> etiqueta normalmente contiene una <WideEntries> etiqueta. La <WideEntries> etiqueta contiene una o varias <WideEntry> etiquetas. Una <WideEntry> etiqueta contiene una <WideItem> etiqueta.

Una <WideItem> etiqueta debe incluir una <PropertyName> etiqueta o una <ScriptBlock> etiqueta. Una <PropertyName> etiqueta especifica la propiedad que se va a mostrar en la ubicación especificada de la vista. Una <ScriptBlock> etiqueta especifica un script para evaluar y mostrar en la ubicación especificada de la vista.

Una <WideItem> etiqueta puede contener una <FormatString> etiqueta que especifica cómo mostrar la propiedad.

Etiqueta CustomControl

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

Uso del archivo Format.ps1xml de seguimiento

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

FormatFileLoading
FormatViewBinding

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

Firma de un archivo Format.ps1xml

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

XML de ejemplo para una vista personalizada de tabla de formato

En el ejemplo XML siguiente se crea una Format-Table vista personalizada para los objetos 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 cmdlets y Export-FormatData para generar un .ps1xml archivo. A continuación, edite .ps1xml el archivo para crear el código de la vista personalizada. El .ps1xml archivo se puede almacenar en cualquier directorio al que pueda acceder PowerShell. Por ejemplo, un subdirectorio de $HOME.

Una vez creado el .ps1xml 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, Format-Table se produce un error.

Use Format-Table con el parámetro View para especificar el nombre de la vista 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.