Add-Content

模組:

Microsoft.PowerShell.Management

新增內容至指定的項目，例如將文字新增到檔案。

Syntax

Add-Content
   [-Path] <string[]>
   [-Value] <Object[]>
   [-PassThru]
   [-Filter <string>]
   [-Include <string[]>]
   [-Exclude <string[]>]
   [-Force]
   [-Credential <pscredential>]
   [-WhatIf]
   [-Confirm]
   [-NoNewline]
   [-Encoding <Encoding>]
   [-AsByteStream]
   [-Stream <string>]
   [<CommonParameters>]

Add-Content
   [-Value] <Object[]>
   -LiteralPath <string[]>
   [-PassThru]
   [-Filter <string>]
   [-Include <string[]>]
   [-Exclude <string[]>]
   [-Force]
   [-Credential <pscredential>]
   [-WhatIf]
   [-Confirm]
   [-NoNewline]
   [-Encoding <Encoding>]
   [-AsByteStream]
   [-Stream <string>]
   [<CommonParameters>]

Description

Cmdlet 會將 Add-Content 內容附加至指定的項目或檔案。 內容可以從管線傳入，或使用 Value 參數來指定。

如果您需要為下列範例建立檔案或目錄，請參閱 New-Item。

範例

範例 1：將字串新增至所有文本檔，但例外狀況

本範例會將值附加至目前目錄中的文本檔，但會根據其檔名排除檔案。

Add-Content -Path .\*.txt -Exclude help* -Value 'End of file'

Path 參數會指定目前目錄中的所有.txt檔案，但 Exclude 參數會忽略符合指定模式的檔名。 Value 參數會指定寫入檔案的文字字串。

使用 Get-Content 來顯示這些檔案的內容。

範例 2：將日期新增至指定檔案的結尾

本範例會將日期附加至目前目錄中的檔案，並在 PowerShell 控制台中顯示日期。

Add-Content -Path .\DateTimeFile1.log, .\DateTimeFile2.log -Value (Get-Date) -PassThru
Get-Content -Path .\DateTimeFile1.log

Tuesday, May 14, 2019 8:24:27 AM
Tuesday, May 14, 2019 8:24:27 AM
5/14/2019 8:24:27 AM

Cmdlet 會在 Add-Content 當前目錄中建立兩個新的檔案。 Value 參數包含 Cmdlet 的Get-Date輸出。 PassThru 參數會將新增的內容輸出至管線。 因為沒有其他 Cmdlet 可接收輸出，所以會顯示在 PowerShell 控制台中。 Cmdlet Get-Content 會顯示更新的檔案 DateTimeFile1.log。

範例 3：將指定檔案的內容新增至另一個檔案

此範例會從檔案取得內容，並將內容儲存在變數中。 變數可用來將內容附加至另一個檔案。

$From = Get-Content -Path .\CopyFromFile.txt
Add-Content -Path .\CopyToFile.txt -Value $From
Get-Content -Path .\CopyToFile.txt

• Cmdlet 會 Get-Content 取得 的內容 CopyFromFile.txt ，並將內容儲存在變數中 $From 。
• Cmdlet Add-Content 會使用 變數的內容$From來更新CopyToFile.txt檔案。
• Cmdlet Get-Content 會顯示 CopyToFile.txt。

範例 4：使用管線將指定檔案的內容新增至另一個檔案

此範例會從檔案取得內容，並將它傳送至 Add-Content Cmdlet。

Get-Content -Path .\CopyFromFile.txt | Add-Content -Path .\CopyToFile.txt
Get-Content -Path .\CopyToFile.txt

Cmdlet Get-Content 會取得 的內容 CopyFromFile.txt。 結果會以管線傳送至 Add-Content Cmdlet，以更新 CopyToFile.txt。 最後一個 Get-Content Cmdlet 會顯示 CopyToFile.txt。

範例 5：Create 新檔案並複製內容

此範例會建立新的檔案，並將現有檔案的內容複製到新檔案中。

Add-Content -Path .\NewFile.txt -Value (Get-Content -Path .\CopyFromFile.txt)
Get-Content -Path .\NewFile.txt

• Cmdlet 會 Add-Content 使用 Path 和 Value 參數，在當前目錄中建立新的檔案。
• Cmdlet Get-Content 會取得現有檔案的內容， CopyFromFile.txt 並將它傳遞至 Value 參數。 Cmdlet 周圍的 Get-Content 括號可確保命令在命令開始之前 Add-Content 完成。
• Cmdlet Get-Content 會顯示新檔案的內容。 NewFile.txt

範例 6：將內容新增至唯讀檔案

此命令會將值新增至檔案，即使 IsReadOnly 檔案屬性設定為 True也一樣。 建立唯讀檔案的步驟包含在範例中。

New-Item -Path .\IsReadOnlyTextFile.txt -ItemType File
Set-ItemProperty -Path .\IsReadOnlyTextFile.txt -Name IsReadOnly -Value $True
Get-ChildItem -Path .\IsReadOnlyTextFile.txt
Add-Content -Path .\IsReadOnlyTextFile.txt -Value 'Add value to read-only text file' -Force
Get-Content -Path .\IsReadOnlyTextFile.txt

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-ar--         1/28/2019     13:35              0 IsReadOnlyTextFile.txt

• Cmdlet New-Item 會使用 Path 和 ItemType 參數，在當前目錄中建立檔案 IsReadOnlyTextFile.txt 。
• Cmdlet Set-ItemProperty 會使用 Name 和 Value 參數，將檔案的 IsReadOnly 屬性變更為 True。
• Cmdlet Get-ChildItem 會顯示檔案是空的 (0) ，而且具有唯讀屬性 (r) 。
• Cmdlet 會 Add-Content 使用 Path 參數來指定檔案。 Value 參數包含要附加至檔案的文字字串。 Force 參數會將文字寫入唯讀檔案。
• Cmdlet Get-Content 會使用 Path 參數來顯示檔案的內容。

若要移除唯讀屬性，請使用 Set-ItemProperty 命令，並將 Value 參數設定為 False。

範例 7：搭配 Add-Content 使用篩選

您可以指定 Cmdlet 的篩選條件 Add-Content 。 使用篩選來限定 Path 參數時，您必須包含尾端星號 (*) ，以指出路徑的內容。

下列命令會將 「Done」 這個字新增至目錄中所有 *.txt 檔案 C:\Temp 的內容。

Add-Content -Path C:\Temp\* -Filter *.txt -Value "Done"

參數

-AsByteStream

指定內容應讀取為位元組數據流。 此參數是在 PowerShell 6.0 中引進。

當您搭配 Encoding 參數使用 AsByteStream 參數時，就會發生警告。 AsByteStream 參數會忽略任何編碼，而輸出會以位元組數據流的形式傳回。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Confirm

在執行 Cmdlet 前提示您確認。

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Credential

注意

任何與 PowerShell 一起安裝的提供者都不支援此參數。 若要在執行此 Cmdlet 時模擬其他使用者，或提高您的認證，請使用 Invoke-Command。

Type:	PSCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Encoding

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

Encoding 是 FileSystem 提供者新增至 Cmdlet 的 Add-Content 動態參數。 此參數只適用於檔案系統磁碟機。

此參數可接受的值如下所示：

• ascii：使用 ASCII (7 位) 字元集的編碼方式。
• bigendianunicode：使用大位元組位元組順序以UTF-16格式編碼。
• bigendianutf32：使用大位元組位元組順序以UTF-32格式編碼。
• oem：使用 MS-DOS 和控制台程式的預設編碼方式。
• unicode：使用位元組由小到大的順序，以UTF-16格式編碼。
• utf7：以 UTF-7 格式編碼。
• utf8：以 UTF-8 格式編碼。
• utf8BOM：使用位元組順序標記 (BOM) 以 UTF-8 格式編碼
• utf8NoBOM：以 UTF-8 格式編碼，不含位元組順序標記 (BOM)
• utf32：以 UTF-32 格式編碼。

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

注意

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

Type:	Encoding
Accepted values:	ASCII, BigEndianUnicode, BigEndianUTF32, OEM, Unicode, UTF7, UTF8, UTF8BOM, UTF8NoBOM, UTF32
Position:	Named
Default value:	UTF8NoBOM
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Exclude

指定此 Cmdlet 在作業中排除的專案或專案，做為字串陣列。 此參數的值會限定 Path 參數。 輸入路徑元素或模式，例如 *.txt。 允許使用萬用字元。 Exclude 參數只有在 命令包含項目的內容時有效，例如 C:\Windows\*，其中通配符會指定目錄的內容 C:\Windows 。

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	True

-Filter

指定篩選條件以限定 Path 參數。 FileSystem 提供者是唯一支援使用篩選的已安裝 PowerShell 提供者。 您可以在 about_Wildcards 中找到 FileSystem 篩選語言的語法。 篩選比其他參數更有效率，因為當 Cmdlet 取得物件時，提供者會套用它們，而不是在擷取對象之後讓 PowerShell 篩選物件。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	True

-Force

覆寫唯讀屬性，可讓您新增內容至唯讀檔案。 例如， Force 會覆寫唯讀屬性，但不會變更檔案許可權。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Include

以字串陣列指定此 Cmdlet 在作業中納入的項目。 此參數的值會限定 Path 參數。 輸入路徑元素或模式，例如 "*.txt"。 允許使用萬用字元。 Include 參數只有在命令包含項目的內容時有效，例如 C:\Windows\*，其中通配符會指定目錄的內容C:\Windows。

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	True

-LiteralPath

指定一個或多個位置的路徑。 LiteralPath 的值會完全依照其類型使用。 沒有字元會被視為萬用字元。 如果路徑包含逸出字元，請將它括在單引號中。 單引號會告訴PowerShell不要將任何字元解譯為逸出序列。

如需詳細資訊，請參閱 about_Quoting_Rules。

Type:	String[]
Aliases:	PSPath, LP
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-NoNewline

表示此 Cmdlet 不會將新行或歸位字元新增至內容。

輸入物件的字串表示會串連以形成輸出。 輸出字串之間不會插入空格或換行符。 最後一個輸出字串之後不會新增任何換行符。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PassThru

傳回代表新增內容的物件。 根據預設，此 Cmdlet 不會產生任何輸出。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Path

指定要接收其他內容的項目路徑。 允許使用萬用字元。 路徑需為項目的路徑，而非容器的路徑。 例如，您必須指定一或多個檔案的路徑，而非目錄的路徑。 如果您指定多個路徑，請使用逗號來分隔路徑。

Type:	String[]
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	True

-Stream

注意

此參數僅適用於 Windows。

指定內容的替代數據流。 如果數據流不存在，此 Cmdlet 會建立它。 不支援通配符。

Stream 是 FileSystem 提供者新增至 Add-Content的動態參數。 此參數只適用於檔案系統磁碟機。

您可以使用 Add-Content Cmdlet 來變更任何替代資料串流的內容， 例如 Zone.Identifier。 不過，我們不建議這麼做，以消除封鎖從因特網下載之檔案的安全性檢查。 如果您確認下載的檔案安全，請使用 Unblock-File Cmdlet。

此參數是在 PowerShell 3.0 中引進。 從 PowerShell 7.2 起， Add-Content 可以在檔案和目錄上以替代數據流為目標。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Value

指定要新增的內容。 輸入引號字串，例如 此數據僅供內部使用，或指定包含內容的物件，例如產生的 DateTime 物件 Get-Date 。

您無法藉由輸入檔案路徑來指定檔案的內容，因為路徑只是字串。 您可以使用 Get-Content 命令來取得內容，並將其傳遞至 Value 參數。

Type:	Object[]
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-WhatIf

顯示執行 Cmdlet 後會發生的情況。 不會執行此 Cmdlet。

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

輸入

Object

您可以使用管線將值傳送至 Add-Content。

PSCredential

您可以使用管線將認證傳送至 Add-Content。

輸出

None

根據預設，此 Cmdlet 不會傳回任何輸出。

String

當您使用 PassThru 參數時，此 Cmdlet 會傳回代表內容的 System.String 物件。

備註

PowerShell 包含的下列別名 Add-Content：

• Windows：

  • ac

• 當您使用管線將對象傳送至 Add-Content時，物件會先轉換成字串，再將它新增至專案。 物件類型決定字串格式，但是格式可能會不同於物件的預設顯示。 若要控制字串格式，請使用傳送 Cmdlet 的格式化參數。

• 此 Add-Content Cmdlet 的設計目的是要處理任何提供者所公開的數據。 若要列出工作階段中可用的提供者，請輸入 Get-PSProvider。 如需詳細資訊，請參閱 about_Providers。

相關連結

• about_Aliases
• about_Providers
• Clear-Content
• Get-Content
• Get-Item
• New-Item
• Set-Content