Condividi tramite

about_Format.ps1xml

Breve descrizione

A partire da PowerShell 6, le visualizzazioni predefinite per gli oggetti sono definite nel codice sorgente di PowerShell.

È possibile creare file di Format.ps1xml personalizzati per modificare la visualizzazione degli oggetti o per definire le visualizzazioni predefinite per i nuovi tipi di oggetto creati in PowerShell.

Descrizione lunga

A partire da PowerShell 6, le visualizzazioni predefinite vengono definite nel codice sorgente di PowerShell. I file Format.ps1xml di PowerShell 5.1 e versioni precedenti non esistono in PowerShell 6 e versioni successive.

Il codice sorgente di PowerShell definisce la visualizzazione predefinita degli oggetti nella console di PowerShell. È possibile creare file di Format.ps1xml personalizzati per modificare la visualizzazione degli oggetti o per definire le visualizzazioni predefinite per i nuovi tipi di oggetto creati in PowerShell.

Quando PowerShell visualizza un oggetto, usa i dati nei file di formattazione strutturati per determinare la visualizzazione predefinita dell'oggetto. I dati nei file di formattazione determinano se il rendering dell'oggetto viene eseguito in una tabella o in un elenco e determina quali proprietà vengono visualizzate per impostazione predefinita.

La formattazione influisce solo sulla visualizzazione. Non influisce sulle proprietà dell'oggetto passate alla pipeline o sul modo in cui vengono passate. Format.ps1xml file non possono essere usati per personalizzare il formato di output per le tabelle hash.

Un file di formattazione .ps1xml può definire quattro visualizzazioni diverse di ogni oggetto:

  • Tavolo
  • Lista
  • Largo
  • Personalizzato

Ad esempio, quando l'output di un comando Get-ChildItem viene inviato tramite pipe a un comando Format-List, Format-List usa la visualizzazione elenco definita nel codice sorgente per determinare come visualizzare gli oggetti file e cartelle come elenco.

Quando un file di formattazione include più visualizzazioni di un oggetto, PowerShell applica la prima visualizzazione trovata.

In un file di Format.ps1xml personalizzato, una vista viene definita da un set di tag XML che descrivono il nome della visualizzazione, il tipo di oggetto a cui può essere applicato, le intestazioni di colonna e le proprietà visualizzate nel corpo della visualizzazione. Il formato nei file di Format.ps1xml viene applicato subito prima che i dati vengano presentati all'utente.

Creazione di nuovi file Format.ps1xml

Per modificare il formato di visualizzazione di una visualizzazione oggetto esistente o per aggiungere visualizzazioni per nuovi oggetti, creare file di Format.ps1xml personalizzati e quindi aggiungerli alla sessione di PowerShell.

Per creare un file di per definire una visualizzazione personalizzata, usare i cmdlet Get-FormatData e Export-FormatData. Usare un editor di testo per modificare il file. Il file può essere salvato in qualsiasi directory a cui PowerShell può accedere, ad esempio una sottodirectory di $HOME.

Per modificare la formattazione di una visualizzazione corrente, individuare la visualizzazione nel file di formattazione e quindi usare i tag per modificare la visualizzazione. Per creare una vista per un nuovo tipo di oggetto, creare una nuova visualizzazione o usare una vista esistente come modello. I tag sono descritti nella sezione successiva. È quindi possibile eliminare tutte le altre visualizzazioni nel file in modo che le modifiche siano evidenti a chiunque esamini il file.

Dopo aver salvato le modifiche, usare il Update-FormatData per aggiungere il nuovo file alla sessione di PowerShell. Se si vuole che la vista abbia la precedenza su una vista definita nei file predefiniti, usare il parametro PrependPath. Update-FormatData influisce solo sulla sessione corrente. Per apportare la modifica a tutte le sessioni future, aggiungere il comando Update-FormatData al profilo di PowerShell.

Esempio: Aggiungere dati del calendario agli oggetti culturali

Questo esempio illustra come modificare la formattazione degli oggetti cultura System.Globalization.CultureInfo generati dal cmdlet Get-Culture nella sessione corrente di PowerShell. I comandi nell'esempio aggiungono la proprietà Calendar alla visualizzazione predefinita in formato tabella degli oggetti culturali.

Per iniziare, ottieni i dati di formato dal file di codice sorgente e crea un file Format.ps1xml che contenga la visualizzazione corrente degli oggetti culturali.

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

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

Aprire il file CultureInfo.Format.ps1xml in qualsiasi editor di testo o XML, ad esempio Visual Studio Code. Il codice XML seguente definisce le visualizzazioni dell'oggetto CultureInfo.

Il file CultureInfo.Format.ps1xml dovrebbe essere simile all'esempio seguente:

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

Creare una nuova colonna per la proprietà Calendario aggiungendo un nuovo set di tag <TableColumnHeader>. Il valore della proprietà Calendario può essere lungo, quindi si consiglia di specificare un valore di 45 caratteri come <Width>.

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

Aggiungere un nuovo elemento di colonna per Calendario nelle righe della tabella utilizzando i tag <TableColumnItem> e <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>

Salvare e chiudere il file. Usare Update-FormatData per aggiungere il nuovo file di formato alla sessione di PowerShell corrente.

In questo esempio viene utilizzato il parametro PrependPath per inserire il nuovo file in un ordine di precedenza superiore rispetto al file originale. Per altre informazioni, vedere Update-FormatData.

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

Per testare la modifica, digitare ed esaminare l'output che include la proprietà Calendar.

Get-Culture

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

XML nei file Format.ps1xml

La definizione completa dello schema è disponibile in Format.xsd nel repository del codice sorgente di PowerShell in GitHub.

La sezione ViewDefinitions di ogni file di contiene i tag che definiscono ogni visualizzazione. Un tag <View> tipico include i tag seguenti:

  • <Name> identifica il nome della visualizzazione.
  • <ViewSelectedBy> specifica il tipo di oggetto o i tipi a cui si applica la vista.
  • <GroupBy> specifica il modo in cui gli elementi nella visualizzazione verranno combinati in gruppi.
  • <TableControl>, <ListControl>, <WideControl>e <CustomControl> contengono i tag che specificano la modalità di visualizzazione di ogni elemento.

Tag ViewSelectedBy

Il tag <ViewSelectedBy> può contenere un tag <TypeName> per ogni tipo di oggetto a cui si applica la visualizzazione. In alternativa, può contenere un tag <SelectionSetName> che fa riferimento a un set di selezione definito altrove usando un tag <SelectionSet>.

Raggruppa per tag

Il tag <GroupBy> contiene un tag <PropertyName> che specifica la proprietà dell'oggetto in base alla quale raggruppare gli elementi. Contiene anche un tag <Label> che specifica una stringa da utilizzare come etichetta per ogni gruppo o un tag <CustomControlName> che fa riferimento a un controllo personalizzato definito altrove usando un tag <Control>. Il tag <Control> contiene un tag <Name> e un tag <CustomControl>.

TableControlTag

Il tag <TableControl> contiene in genere tag <TableHeaders> e <TableRowEntries> che definiscono la formattazione per le teste e le righe della tabella. Il tag <TableHeaders> contiene in genere tag <TableColumnHeader> contenenti tag <Label>, <Width>e <Alignment>. Il tag <TableRowEntries> contiene tag <TableRowEntry> per ogni riga della tabella. Il tag <TableRowEntry> contiene un tag <TableColumnItems> che contiene un tag <TableColumnItem> per ogni colonna della riga. In genere, il tag <TableColumnItem> contiene un tag <PropertyName> che identifica la proprietà dell'oggetto da visualizzare nella posizione definita oppure un tag <ScriptBlock> che contiene codice script che calcola un risultato che deve essere visualizzato nella posizione.

Nota

Gli scriptblock possono essere usati anche altrove in posizioni in cui i risultati calcolati possono essere utili.

Il tag <TableColumnItem> può contenere anche un tag <FormatString> che specifica come verrà visualizzata la proprietà o i risultati calcolati.

Tag ListControl

Il tag <ListControl> contiene in genere un tag <ListEntries>. Il tag <ListEntries> contiene un tag <ListEntry>. Il tag <ListEntry> contiene un tag <ListItems>. Il tag <ListItems> contiene tag <ListItem> che contengono tag <PropertyName>. I tag <PropertyName> specificano la proprietà dell'oggetto da visualizzare nella posizione specificata nell'elenco. Se la selezione della visualizzazione viene definita usando un set di selezione, i tag <ListControl> e <ListEntry> possono contenere anche un tag <EntrySelectedBy> che contiene uno o più tag <TypeName>. Questi tag <TypeName> specificano il tipo di oggetto che il tag <ListControl> è destinato a visualizzare.

Tag WideControl

Il tag <WideControl> contiene in genere un tag <WideEntries>. Il tag <WideEntries> contiene uno o più tag <WideEntry>. Un tag <WideEntry> contiene un tag <WideItem>.

Un tag <WideItem> deve includere un tag <PropertyName> o un tag <ScriptBlock>. Un tag <PropertyName> specifica la proprietà da visualizzare nella posizione specificata nella visualizzazione. Un tag <ScriptBlock> specifica uno script da valutare e visualizzare nella posizione specificata nella visualizzazione.

Un tag <WideItem> può contenere un tag <FormatString> che specifica come visualizzare la proprietà.

Tag CustomControl

Il <CustomControl> tag consente di usare uno scriptblock per definire un formato. Un tag <CustomControl> contiene in genere un tag <CustomEntries> che contiene più tag <CustomEntry>. Ogni tag <CustomEntry> contiene un tag <CustomItem> che può contenere un'ampia gamma di tag che specificano il contenuto e la formattazione della posizione specificata nella visualizzazione, inclusi <Text>, <Indentation>, <ExpressionBinding>e tag <NewLine>.

Traccia dell'uso del file Format.ps1xml

Per rilevare gli errori nel caricamento o nell'applicazione dei file di , usare il cmdlet con uno dei componenti di formato seguenti come valore del parametro Name :

  • FormatFileLoading
  • FormatViewBinding

Per altre informazioni, vedere Trace-Command e Get-TraceSource.

Firma di un file Format.ps1xml

Per proteggere gli utenti del file di Format.ps1xml, firmare il file usando una firma digitale. Per altre informazioni, vedere about_Signing.

XML di esempio per una vista personalizzata Format-Table

Nell'esempio XML seguente viene creata una vista personalizzata Format-Table per gli oggetti System.IO.DirectoryInfo e System.IO.FileInfo creati da Get-ChildItem. La vista personalizzata è denominata MyGciView e aggiunge la colonna CreationTime alla tabella.

Per creare la visualizzazione personalizzata, usare i cmdlet Get-FormatData e Export-FormatData per generare un file .ps1xml. Modificare quindi il file .ps1xml per creare il codice per la visualizzazione personalizzata. Il file .ps1xml può essere archiviato in qualsiasi directory a cui PowerShell può accedere. Ad esempio, una sottodirectory di $HOME.

Dopo aver creato il file .ps1xml, usare il cmdlet Update-FormatData per includere la visualizzazione nella sessione di PowerShell corrente. In alternativa, aggiungere il comando di aggiornamento al profilo di PowerShell se è necessaria la visualizzazione disponibile in tutte le sessioni di PowerShell.

Per questo esempio, la vista personalizzata deve utilizzare il formato di tabella; in caso contrario, Format-Table ha esito negativo.

Usare Format-Table con il parametro View per specificare il nome della vista personalizzata, MyGciViewe formattare l'output della tabella con la colonna CreationTime. Per un esempio di come viene eseguito il comando, vedere Format-Table.

Nota

Sebbene sia possibile ottenere il codice XML di formattazione dal codice sorgente per creare una visualizzazione personalizzata, potrebbe essere necessario uno sviluppo maggiore per ottenere il risultato desiderato.

Nel comando Get-FormatData seguente è disponibile un'alternativa per il parametro PowerShellVersion per assicurarsi che vengano restituite tutte le informazioni di formattazione locali. Usare -PowerShellVersion $PSVersionTable.PSVersion anziché una versione specifica di 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>

Vedere anche

  • Last updated on