Tee-Object

模組:: Microsoft.PowerShell.Utility Module

將命令輸出儲存在檔案或變數中，並將它傳送至管線。

語法

File (預設值)

Tee-Object
    [-FilePath] <String>
    [[-Encoding] <Encoding>]
    [-InputObject <PSObject>]
    [-Append]
    [<CommonParameters>]

LiteralFile

Tee-Object
    [[-Encoding] <Encoding>]
    -LiteralPath <String>
    [-InputObject <PSObject>]
    [<CommonParameters>]

Variable

Tee-Object
    -Variable <String>
    [-InputObject <PSObject>]
    [<CommonParameters>]

Description

Tee-Object Cmdlet 會在兩個方向上寫入輸出。它會將輸出儲存在檔案或變數中，並將輸出傳送至管線。如果是管線中的最後一個命令，則 Tee-Object 命令輸出會顯示在主控台中。

在內部， Tee-Object 使用和 Set-VariableOut-File 命令。這些命令支援 WhatIf 參數。此 Tee-Object 命令不支援 WhatIf 參數。不過，如果您包裝 Tee-Object 在支援 WhatIf 參數的腳本或函式中， Tee-Object 則會將 WhatIf 的狀態傳遞至和 Set-VariableOut-File 命令。

範例

範例 1：將進程輸出至檔案和控制台

這個範例會取得計算機上執行的進程清單，並將結果傳送至檔案。因為未指定第二個路徑，因此進程也會顯示在控制台中。

Get-Process | Tee-Object -FilePath "C:\Test1\testfile2.txt"

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)    Id ProcessName
-------  ------    -----      ----- -----   ------    -- -----------
83       4     2300       4520    39     0.30    4032 00THotkey
272      6     1400       3944    34     0.06    3088 alg
81       3      804       3284    21     2.45     148 ApntEx
81       4     2008       5808    38     0.75    3684 Apoint
...

範例 2：將處理程序輸出至變數和 'Select-Object'

這個範例會取得電腦上執行的進程清單、將它們儲存至 $proc 變數，並透過管線將行程傳送至 Select-Object。

Get-Process notepad | Tee-Object -Variable proc | Select-Object ProcessName, Handles

ProcessName                              Handles
-----------                              -------
notepad                                  43
notepad                                  37
notepad                                  38
notepad                                  38

Select-Object Cmdlet 會選取 ProcessName 和句柄屬性。請注意，$proc 變數包含 Get-Process傳回的預設資訊。

範例 3：將系統檔案輸出至兩個記錄檔

本範例會將系統檔案的清單儲存在兩個記錄檔中，一個累計檔案和一個目前的檔案。

Get-ChildItem -Path D: -File -System -Recurse |
  Tee-Object -FilePath "C:\test\AllSystemFiles.txt" -Append |
    Out-File C:\test\NewSystemFiles.txt

命令會使用 Get-ChildItem Cmdlet 對 D：磁碟驅動器上的系統檔案執行遞歸搜尋。管線運算符（|）會將清單傳送至 Tee-Object，它會將清單附加至 AllSystemFiles.txt 檔案，並將清單向下傳遞至 Out-File Cmdlet，以將清單儲存在 NewSystemFiles.txt file中。

範例 4：將輸出列印至主控台，並在管線中使用

這個範例會取得資料夾中的檔案、將它們列印到主控台，然後篩選具有已定義前端元數據區塊的檔案。最後，它會列出具有正面問題的文章名稱。

$consoleDevice = if ($IsWindows) {
    '\\.\CON'
} else {
    '/dev/tty'
}
$frontMatterPattern = '(?s)^---(?<FrontMatter>.+)---'

$articles = Get-ChildItem -Path .\reference\7.4\PSReadLine\About\ |
    Tee-Object -FilePath $consoleDevice |
    Where-Object {
        (Get-Content $_ -Raw) -match $frontMatterPattern
    }

$articles.Name

    Directory: C:\code\docs\PowerShell-Docs\reference\7.4\PSReadLine\About

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---          12/13/2022 11:37 AM            384 .markdownlint.yaml
-a---           4/25/2023 11:28 AM          40194 about_PSReadLine_Functions.md
-a---           4/25/2023 10:58 AM          10064 about_PSReadLine.md

about_PSReadLine_Functions.md
about_PSReadLine.md

此範例會將 $consoleDevice 變數設定為目前終端機控制台裝置的值。在 Windows 上，您可以將輸出重新導向至 \\.\CON 檔案路徑，以寫入目前的控制台裝置。在非 Windows 系統上，您可以使用 /dev/tty filepath。

然後，它會將 $frontMatterPattern 變數設定為正則表示式，該正則表示式會在字串以三個破折號（---）開頭時相符，並在另外三個破折號之前有任何內容。當此模式符合發行項的內容時，發行項具有定義的前端元數據區塊。

接下來，此範例會使用 Get-ChildItem 來擷取 About 資料夾中的每個檔案。 Tee-Object 使用 fileName 參數，將管線結果列印至控制台。 Where-Object 以單一字串的形式取得其內容，並使用的 Get-Content 參數，並將該字串與 $frontMatterPattern進行比較，以篩選檔案。

最後，此範例會列印資料夾中已定義前端元數據區塊的檔名。

範例 5：在指令碼中使用具有 WhatIf 參數的 'Tee-Object'

此 Tee-Object 命令不支援 WhatIf 參數。不過，如果您包裝 Tee-Object 在支援 WhatIf 參數的腳本或函式中， Tee-Object 則會將 WhatIf 的狀態傳遞給 Set-Variable 內部使用的和 Out-File 命令。

PS> function Test-Tee {
    [Cmdletbinding(SupportsShouldProcess)]
    Param()
    $true|tee -Variable b
    "Variable `$b is set to '$b'"
}

PS> Test-Tee

True
Variable $b is set to 'True'

PS> Test-Tee -WhatIf
True
What if: Performing the operation "Set variable" on target "Name: b Value: True".
Variable $b is set to ''

參數

-Append

表示 Cmdlet 會將輸出附加至指定的檔案。如果沒有此參數，新內容會取代檔案中任何現有的內容，而不會發出警告。

此參數是在 Windows PowerShell 3.0 中引進的。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False

參數集

File

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Encoding

指定目標檔案的編碼類型。預設值是 utf8NoBOM。

此參數可接受的值如下：

ascii：使用 ASCII （7 位）字元集的編碼方式。
ansi：使用符合當前文化特性的 ANSI 代碼頁的編碼方式。此選項已在PowerShell 7.4中新增。
bigendianunicode：使用高位元組序以 UTF-16 格式編碼。
oem：使用 MS-DOS 和控制台程序的預設編碼方式。
unicode：使用小端位元組順序，以UTF-16格式進行編碼。
utf7：以UTF-7格式編碼。
utf8：以UTF-8格式編碼。
utf8BOM：以 UTF-8 格式（含位元組順序標記 BOM）編碼
utf8NoBOM：以 UTF-8 格式編碼，不含位元組順序標記【BOM】
utf32：以UTF-32格式編碼。

從 PowerShell 6.2 開始，編碼參數也允許已註冊代碼頁的數值識別元（例如 -Encoding 1251）或已註冊代碼頁的字串名稱（例如 -Encoding "windows-1251"）。如需詳細資訊，請參閱 Encoding.CodePage的 .NET 檔。

從 PowerShell 7.4 開始，您可以使用 Ansi 參數的值，傳遞目前文化的 ANSI 代碼頁的數值 ID，而不需要手動指定。

此參數是在 PowerShell 7.2 中引進的。

備註

UTF-7* 不再建議使用。自 PowerShell 7.1 起，如果您為 utf7 參數指定，則會撰寫警告。

參數屬性

類型:	Encoding
預設值:	UTF8NoBOM
接受的值:	ASCII, BigEndianUnicode, OEM, Unicode, UTF7, UTF8, UTF8BOM, UTF8NoBOM, UTF32
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	1
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-FilePath

指定允許此 Cmdlet 將物件儲存到通配符的檔案，但必須解析為單一檔案。

從 PowerShell 7 開始，當您在 Windows 或非 Windows 系統上將 FilePath 指定為 \\.\CON/dev/tty，InputObject 會列印在控制台中。這些檔案路徑會對應到系統上目前終端機的控制台裝置，讓您列印 InputObject，並使用一個命令將它傳送至輸出數據流。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	True
不要顯示:	False
別名:	路徑

參數集

File

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-InputObject

指定要儲存和顯示的物件。輸入包含物件的變數，或輸入取得物件的命令或表達式。您也可以使用管線將物件傳送至 Tee-Object。

當您搭配使用 Tee-Object 參數時，Tee-Object即使值是集合，InputObject 值也會被視為單一物件。

參數屬性

類型:	PSObject
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	True
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-LiteralPath

指定這個 Cmdlet 儲存物件的目標檔案。與 FilePath不同，LiteralPath 參數的值會被完全按其鍵入方式使用。不會將任何字元解譯為通配符。如果路徑包含逸出字元，請以單引弧括住它。單引號會告知PowerShell不要將任何字元解譯為逸出序列。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	PSPath, LP

參數集

LiteralFile

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Variable

指定 Cmdlet 將物件儲存至的變數。輸入不含上述貨幣符號的變數名稱（$）。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

Variable

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。如需詳細資訊，請參閱 about_CommonParameters。

輸入

PSObject

您可以將物件通過管線傳送至此 Cmdlet。

輸出

PSObject

此 Cmdlet 會傳回其重新導向的物件。

備註

PowerShell 包含下列 Tee-Object的別名：

窗戶：
- tee

您也可以使用 Out-File Cmdlet 或重新導向運算符，這兩者都會將輸出儲存在檔案中，但不會將輸出傳送至管線。

從 PowerShell 6 開始，Tee-Object 寫入檔案時，會使用無 BOM 的 UTF-8 編碼。如果您需要不同的編碼方式，請使用 Out-File Cmdlet 搭配 Encoding 參數。

意見反應

此頁面對您有幫助嗎？

共用方式為

Tee-Object

語法

File (預設值)

LiteralFile

Variable

Description

範例

範例 1：將進程輸出至檔案和控制台

範例 2：將處理程序輸出至變數和 'Select-Object'

範例 3：將系統檔案輸出至兩個記錄檔

範例 4：將輸出列印至主控台，並在管線中使用

範例 5：在指令碼中使用具有 **WhatIf** 參數的 'Tee-Object'

參數

-Append

參數屬性

參數集

-Encoding

參數屬性

參數集

-FilePath

參數屬性

參數集

-InputObject

參數屬性

參數集

-LiteralPath

參數屬性

參數集

-Variable

參數屬性

參數集

CommonParameters

輸入

PSObject

輸出

PSObject

備註

相關連結

意見反應

範例 5：在指令碼中使用具有 WhatIf 參數的 'Tee-Object'