Tentang_Format.ps1xml

Deskripsi singkat

Dimulai di PowerShell 6, tampilan default untuk objek ditentukan dalam kode sumber PowerShell.

Anda dapat membuat file Format.ps1xml Anda sendiri untuk mengubah tampilan objek atau untuk menentukan tampilan default untuk jenis objek baru yang Anda buat di PowerShell.

Deskripsi panjang

Dimulai di PowerShell 6, tampilan default ditentukan dalam kode sumber PowerShell. File Format.ps1xml dari PowerShell 5.1 dan versi yang lebih lama tidak ada di PowerShell 6 dan versi yang lebih baru.

Kode sumber PowerShell menentukan tampilan default objek di konsol PowerShell. Anda dapat membuat file Format.ps1xml Anda sendiri untuk mengubah tampilan objek atau untuk menentukan tampilan default untuk jenis objek baru yang Anda buat di PowerShell.

Saat PowerShell menampilkan objek, powerShell menggunakan data dalam file pemformatan terstruktur untuk menentukan tampilan default objek. Data dalam file pemformatan menentukan apakah objek dirender dalam tabel atau dalam daftar, dan menentukan properti mana yang ditampilkan secara default.

Pemformatan hanya memengaruhi tampilan. Ini tidak memengaruhi properti objek mana yang diteruskan ke alur atau bagaimana properti tersebut diteruskan. Format.ps1xml file tidak dapat digunakan untuk menyesuaikan format output untuk tabel hash.

File pemformatan .ps1xml dapat menentukan empat tampilan berbeda dari setiap objek:

Meja
Daftar
Lebar
Kustom

Misalnya, ketika output perintah Get-ChildItem disalurkan ke perintah Format-List, Format-List menggunakan tampilan daftar yang ditentukan dalam kode sumber untuk menentukan cara menampilkan objek file dan folder sebagai daftar.

Saat file pemformatan menyertakan lebih dari satu tampilan objek, PowerShell menerapkan tampilan pertama yang ditemukannya.

Dalam file Format.ps1xml kustom, tampilan ditentukan oleh sekumpulan tag XML yang menjelaskan nama tampilan, jenis objek yang dapat diterapkan, header kolom, dan properti yang ditampilkan dalam isi tampilan. Format dalam file Format.ps1xml diterapkan tepat sebelum data disajikan kepada pengguna.

Membuat file Format.ps1xml baru

Untuk mengubah format tampilan tampilan objek yang sudah ada, atau untuk menambahkan tampilan untuk objek baru, buat file Format.ps1xml Anda sendiri, lalu tambahkan ke sesi PowerShell Anda.

Untuk membuat file untuk menentukan tampilan kustom, gunakan cmdlet Get-FormatData dan Export-FormatData. Gunakan editor teks untuk mengedit file. File dapat disimpan ke direktori apa pun yang dapat diakses PowerShell, seperti subdirektori $HOME.

Untuk mengubah pemformatan tampilan saat ini, temukan tampilan dalam file pemformatan, lalu gunakan tag untuk mengubah tampilan. Untuk membuat tampilan untuk jenis objek baru, buat tampilan baru, atau gunakan tampilan yang sudah ada sebagai model. Tag dijelaskan di bagian berikutnya. Anda kemudian dapat menghapus semua tampilan lain dalam file sehingga perubahannya jelas bagi siapa pun yang memeriksa file.

Setelah Anda menyimpan perubahan, gunakan Update-FormatData untuk menambahkan file baru ke sesi PowerShell Anda. Jika Anda ingin tampilan Anda lebih diutamakan daripada tampilan yang ditentukan dalam file bawaan, gunakan parameter PrependPath. Update-FormatData hanya memengaruhi sesi saat ini. Untuk membuat perubahan pada semua sesi mendatang, tambahkan perintah Update-FormatData ke profil PowerShell Anda.

Contoh: Menambahkan data kalender ke objek budaya

Contoh ini menunjukkan cara mengubah pemformatan objek budaya System.Globalization.CultureInfo yang dihasilkan oleh cmdlet Get-Culture dalam sesi PowerShell saat ini. Perintah dalam contoh tersebut menambahkan properti Kalender ke tampilan tabel default dari objek kebudayaan.

Untuk memulai, dapatkan data format dari file kode sumber dan buat file Format.ps1xml yang berisi tampilan objek budaya saat ini.

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

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

Buka file CultureInfo.Format.ps1xml di XML atau editor teks apa pun, seperti Visual Studio Code. XML berikut mendefinisikan tampilan objek CultureInfo.

File CultureInfo.Format.ps1xml akan terlihat seperti sampel berikut:

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

Buat kolom baru untuk properti Kalender dengan menambahkan sekumpulan tag baru. Nilai properti Kalender bisa panjang, jadi tentukan nilai 45 karakter sebagai .

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

Tambahkan item kolom baru untuk Kalender di baris tabel menggunakan tag dan :

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

Simpan dan tutup file. Gunakan Update-FormatData untuk menambahkan file format baru ke sesi PowerShell saat ini.

Contoh ini menggunakan parameter prependPath untuk menempatkan file baru dalam urutan prioritas yang lebih tinggi daripada file asli. Untuk informasi selengkapnya, lihat Update-FormatData.

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

Untuk menguji perubahan, ketik dan tinjau output yang menyertakan properti Kalender .

Get-Culture

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

XML dalam file Format.ps1xml

Definisi skema lengkap dapat ditemukan di format.xsd di repositori kode sumber PowerShell di GitHub.

Bagian ViewDefinitions dari setiap file Format.ps1xml berisi tag <View> yang menentukan setiap tampilan. Tag <View> umum mencakup tag berikut:

<Name> mengidentifikasi nama tampilan.
<ViewSelectedBy> menentukan jenis atau jenis objek yang diterapkan tampilan.
<GroupBy> menentukan bagaimana item dalam tampilan akan digabungkan dalam grup.
<TableControl>, <ListControl>, <WideControl>, dan <CustomControl> berisi tag yang menentukan bagaimana setiap item akan ditampilkan.

Tag ViewSelectedBy

Tag <ViewSelectedBy> dapat berisi tag <TypeName> untuk setiap jenis objek tempat tampilan diterapkan. Atau, ini dapat berisi tag <SelectionSetName> yang mereferensikan kumpulan pilihan yang ditentukan di tempat lain dengan menggunakan tag <SelectionSet>.

Tag GroupBy

Tag <GroupBy> berisi tag <PropertyName> yang menentukan properti objek tempat item akan dikelompokkan. Ini juga berisi tag <Label> yang menentukan string yang akan digunakan sebagai label untuk setiap grup atau tag <CustomControlName> yang mereferensikan kontrol kustom yang ditentukan di tempat lain menggunakan tag <Control>. Tag <Control> berisi tag <Name> dan tag <CustomControl>.

TableControlTag

Tag <TableControl> biasanya berisi tag <TableHeaders> dan <TableRowEntries> yang menentukan pemformatan untuk kepala dan baris tabel. Tag <TableHeaders> biasanya berisi tag <TableColumnHeader> yang berisi tag <Label>, <Width>, dan <Alignment>. Tag <TableRowEntries> berisi tag <TableRowEntry> untuk setiap baris dalam tabel. Tag <TableRowEntry> berisi tag <TableColumnItems> yang berisi tag <TableColumnItem> untuk setiap kolom dalam baris. Biasanya, tag <TableColumnItem> berisi tag <PropertyName> yang mengidentifikasi properti objek yang akan ditampilkan di lokasi yang ditentukan, atau tag <ScriptBlock> yang berisi kode skrip yang menghitung hasil yang akan ditampilkan di lokasi.

Nota

Scriptblock juga dapat digunakan di tempat lain di lokasi di mana hasil terhitung dapat berguna.

Tag <TableColumnItem> juga dapat berisi tag <FormatString> yang menentukan bagaimana properti atau hasil terhitung akan ditampilkan.

Tag ListControl

Tag <ListControl> biasanya berisi tag <ListEntries>. Tag <ListEntries> berisi tag <ListEntry>. Tag <ListEntry> berisi tag <ListItems>. Tag <ListItems> berisi tag <ListItem>, yang berisi tag <PropertyName>. Tag <PropertyName> menentukan properti objek yang akan ditampilkan di lokasi yang ditentukan dalam daftar. Jika pilihan tampilan ditentukan menggunakan kumpulan pilihan, tag <ListControl> dan <ListEntry> juga dapat berisi tag <EntrySelectedBy> yang berisi satu atau beberapa tag <TypeName>. Tag <TypeName> ini menentukan jenis objek yang dimaksudkan untuk ditampilkan oleh tag <ListControl>.

Tag WideControl

Tag <WideControl> biasanya berisi tag <WideEntries>. Tag <WideEntries> berisi satu atau beberapa tag <WideEntry>. Tag <WideEntry> berisi satu tag <WideItem>.

Tag <WideItem> harus menyertakan tag <PropertyName> atau tag <ScriptBlock>. Tag <PropertyName> menentukan properti yang akan ditampilkan di lokasi yang ditentukan dalam tampilan. Tag <ScriptBlock> menentukan skrip untuk dievaluasi dan ditampilkan di lokasi yang ditentukan dalam tampilan.

Tag <WideItem> dapat berisi tag <FormatString> yang menentukan cara menampilkan properti.

Tag CustomControl

Tag memungkinkan <CustomControl> Anda menggunakan blokir skrip untuk menentukan format. Tag <CustomControl> biasanya berisi tag <CustomEntries> yang berisi beberapa tag <CustomEntry>. Setiap tag <CustomEntry> berisi tag <CustomItem> yang dapat berisi berbagai tag yang menentukan konten dan pemformatan lokasi yang ditentukan dalam tampilan, termasuk tag <Text>, <Indentation>, <ExpressionBinding>, dan <NewLine>.

Melacak penggunaan file Format.ps1xml

Untuk mendeteksi kesalahan dalam pemuatan atau aplikasi file , gunakan cmdlet dengan salah satu komponen format berikut sebagai nilai parameter Nama :

FormatFileLoading
FormatViewBinding

Untuk informasi selengkapnya, lihat Trace-Command dan Get-TraceSource.

Menandatangani file Format.ps1xml

Untuk melindungi pengguna file Format.ps1xml Anda, tanda tangani file menggunakan tanda tangan digital. Untuk informasi selengkapnya, lihat tentang_Penandatanganan.

Sampel XML untuk tampilan kustom Format-Table

Sampel XML berikut membuat tampilan kustom untuk System.IO.DirectoryInfo dan system.IO.FileInfo objek yang dibuat oleh . Tampilan kustom diberi nama MyGciView dan menambahkan kolom CreationTime ke tabel.

Untuk membuat tampilan kustom, gunakan cmdlet Get-FormatData dan Export-FormatData untuk menghasilkan file .ps1xml. Kemudian, edit file .ps1xml Anda untuk membuat kode untuk tampilan kustom Anda. File .ps1xml dapat disimpan di direktori apa pun yang dapat diakses PowerShell. Misalnya, subdirektori $HOME.

Setelah file .ps1xml dibuat, gunakan cmdlet Update-FormatData untuk menyertakan tampilan dalam sesi PowerShell saat ini. Atau, tambahkan perintah pembaruan ke profil PowerShell Anda jika Anda memerlukan tampilan yang tersedia di semua sesi PowerShell.

Untuk contoh ini, tampilan kustom harus menggunakan format tabel, jika tidak, Format-Table gagal.

Gunakan Format-Table dengan parameter View untuk menentukan nama tampilan kustom, MyGciView, dan format output tabel dengan kolom CreationTime. Untuk contoh bagaimana perintah dijalankan, lihat Format-Tabel.