about_Format.ps1xml

  • Articolo

Descrizione breve

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

È possibile creare file personalizzati Format.ps1xml per modificare la visualizzazione degli oggetti o 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 Format.ps1xml file 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 personalizzati Format.ps1xml per modificare la visualizzazione degli oggetti o 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 i file non possono essere usati per personalizzare il formato di output per le tabelle hash.

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

  • Tabella
  • List
  • Largo
  • Personalizzazione

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

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

In un file personalizzato Format.ps1xml , una vista è 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 Format.ps1xml file 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 personalizzati Format.ps1xml e quindi aggiungerli alla sessione di PowerShell.

Per creare un Format.ps1xml file per definire una visualizzazione personalizzata, usare i cmdlet Get-FormatData ed 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 Update-FormatData per aggiungere il nuovo file alla sessione di PowerShell. Se si vuole che la vista ha 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 Update-FormatData comando al profilo di PowerShell.

Esempio: Aggiungere dati del calendario agli oggetti cultura

In questo esempio viene illustrato come modificare la formattazione degli oggetti cultura System.Globalization.CultureInfo generati dal Get-Culture cmdlet nella sessione di PowerShell corrente. I comandi nell'esempio aggiungono la proprietà Calendar alla visualizzazione tabella predefinita degli oggetti impostazioni cultura.

Per iniziare, ottenere i dati di formato dal file di codice sorgente e creare un Format.ps1xml file contenente la visualizzazione corrente degli oggetti impostazioni cultura.

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

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

Il CultureInfo.Format.ps1xml file 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à Calendar aggiungendo un nuovo set di <TableColumnHeader> tag. Il valore della proprietà Calendar può essere lungo, quindi 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 Calendar nelle righe della tabella usando i <TableColumnItem> tag 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>

Salva e chiudi 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 Get-Culture 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 Format.ps1xml file contiene i <View> tag che definiscono ogni visualizzazione. Un tag tipico <View> include i tag seguenti:

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

Tag ViewSelectedBy

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

Tag GroupBy

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

TableControlTag

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

Nota

I blocchi di script possono essere usati anche altrove in posizioni in cui i risultati calcolati possono essere utili.

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

Tag ListControl

Il <ListControl> tag contiene in genere un <ListEntries> tag. Il <ListEntries> tag contiene un <ListEntry> tag. Il <ListEntry> tag contiene un <ListItems> tag. Il <ListItems> tag contiene <ListItem> tag che contengono <PropertyName> tag. I <PropertyName> tag 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 <ListControl> tag e <ListEntry> possono contenere anche un <EntrySelectedBy> tag che contiene uno o più <TypeName> tag. Questi <TypeName> tag specificano il tipo di oggetto che il <ListControl> tag deve visualizzare.

Tag WideControl

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

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

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

Tag CustomControl

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

Traccia dell'uso del file Format.ps1xml

Per rilevare gli errori nel caricamento o nell'applicazione di Format.ps1xml file, usare il Trace-Command 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 Format.ps1xml file, 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 Format-Table visualizzazione personalizzata 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 Get-FormatData cmdlet e Export-FormatData per generare un .ps1xml file. Modificare quindi il .ps1xml file per creare il codice per la visualizzazione personalizzata. Il .ps1xml file può essere archiviato in qualsiasi directory a cui PowerShell può accedere. Ad esempio, una sottodirectory di $HOME.

Dopo aver creato il .ps1xml file, usare il Update-FormatData cmdlet 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 usare 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, mygciview e 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 seguente Get-FormatData è 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 -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>

Vedi anche