New-Item

模組:

Microsoft.PowerShell.Management

建立新專案。

Syntax

New-Item
   [-Path] <string[]>
   [-ItemType <string>]
   [-Value <Object>]
   [-Force]
   [-Credential <pscredential>]
   [-WhatIf]
   [-Confirm]
   [-UseTransaction]
   [<CommonParameters>]

New-Item
   [[-Path] <string[]>]
   -Name <string>
   [-ItemType <string>]
   [-Value <Object>]
   [-Force]
   [-Credential <pscredential>]
   [-WhatIf]
   [-Confirm]
   [-UseTransaction]
   [<CommonParameters>]

New-Item
   [-Path] <string[]>
   -ConnectionURI <uri>
   [-ItemType <string>]
   [-Value <Object>]
   [-Force]
   [-Credential <pscredential>]
   [-WhatIf]
   [-Confirm]
   [-UseTransaction]
   [-OptionSet <hashtable>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <string>]
   [-SessionOption <SessionOption>]
   [-Port <int>]
   [<CommonParameters>]

New-Item
   [[-Path] <string[]>]
   -Name <string>
   [-ItemType <string>]
   [-Value <Object>]
   [-Force]
   [-Credential <pscredential>]
   [-WhatIf]
   [-Confirm]
   [-UseTransaction]
   [-OptionSet <hashtable>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <string>]
   [-SessionOption <SessionOption>]
   [-ApplicationName <string>]
   [-Port <int>]
   [-UseSSL]
   [<CommonParameters>]

New-Item
   [-Path] <string[]>
   [-ItemType <string>]
   [-Value <Object>]
   [-Force]
   [-Credential <pscredential>]
   [-WhatIf]
   [-Confirm]
   [-UseTransaction]
   [-Options <ScopedItemOptions>]
   [<CommonParameters>]

New-Item
   [[-Path] <string[]>]
   -Name <string>
   [-ItemType <string>]
   [-Value <Object>]
   [-Force]
   [-Credential <pscredential>]
   [-WhatIf]
   [-Confirm]
   [-UseTransaction]
   [-Options <ScopedItemOptions>]
   [<CommonParameters>]

Description

Cmdlet New-Item 會建立新的專案，並設定其值。 可以建立的項目類型取決於專案的位置。 例如，在文件系統中， New-Item 建立檔案和資料夾。 在登錄中， New-Item 建立登錄機碼和專案。

New-Item 也可以設定它所建立之專案的值。 例如，當它建立新的檔案時， New-Item 可以將初始內容新增至檔案。

範例

範例 1：在目前目錄中建立檔案

此命令會在目前目錄中建立名為 「testfile1.txt」 的文字檔。 Path 參數值中的點 （'.'） 表示目前目錄。 Value 參數後面的引號文字會新增至檔案作為內容。

New-Item -Path . -Name "testfile1.txt" -ItemType "file" -Value "This is a text string."

範例 2：建立目錄

此命令會在磁碟驅動器中建立名為 「Logfiles」 的 C: 目錄。 ItemType 參數會指定新項目是目錄，而不是檔案或其他文件系統物件。

New-Item -Path "c:\" -Name "logfiles" -ItemType "directory"

範例 3：建立配置檔

此命令會在變數指定的 $profile 路徑中建立PowerShell配置檔。

您可以使用設定檔來自定義 PowerShell。 $profile 是自動 （內建） 變數，可儲存 「CurrentUser/CurrentHost」 設定檔的路徑和檔名。 根據預設，即使 PowerShell 會為其儲存路徑和檔名，配置檔也不存在。

在此命令中 $profile ，變數代表檔案的路徑。 ItemType 參數會指定命令建立檔案。 Force 參數可讓您在配置檔路徑中建立檔案，即使路徑中的目錄不存在也一般。

建立設定檔之後，您可以在配置檔中輸入別名、函式和腳本，以自定義殼層。

如需詳細資訊，請參閱 about_Automatic_Variables 和 about_Profiles。

New-Item -Path $profile -ItemType "file" -Force

注意

當您使用此方法建立檔案時，產生的檔案會編碼為UTF-8，而沒有位元組順序標記 （BOM）。

範例 4：在不同的目錄中建立目錄

此範例會在 「C：\PS-Test」 目錄中建立新的 Scripts 目錄。

新目錄專案 「Scripts」 的名稱會包含在 Path 參數的值中，而不是在 Name 的值中指定。 如語法所示，任一個命令窗體都是有效的。

New-Item -ItemType "directory" -Path "c:\ps-test\scripts"

範例 5：建立多個檔案

此範例會在兩個不同的目錄中建立檔案。 因為 Path 會採用多個字串，所以您可以使用它來建立多個專案。

New-Item -ItemType "file" -Path "c:\ps-test\test.txt", "c:\ps-test\Logs\test.log"

範例 6：使用通配符在多個目錄中建立檔案

Cmdlet New-Item 支援Path參數中的通配符。 下列命令會在 temp.txt Path參數中通配符指定的所有目錄中建立檔案。

Get-ChildItem -Path C:\Temp\

Directory:  C:\Temp

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
d-----        5/15/2019   6:45 AM        1   One
d-----        5/15/2019   6:45 AM        1   Two
d-----        5/15/2019   6:45 AM        1   Three

New-Item -Path C:\Temp\* -Name temp.txt -ItemType File | Select-Object FullName

FullName
--------
C:\Temp\One\temp.txt
C:\Temp\Three\temp.txt
C:\Temp\Two\temp.txt

Cmdlet Get-ChildItem 會顯示目錄底下的三個 C:\Temp 目錄。 使用通配符時， New-Item Cmdlet 會在 temp.txt 目前目錄下的所有目錄中建立檔案。 Cmdlet 會 New-Item 輸出您所建立的專案，其會透過管道傳送來 Select-Object 驗證新建立檔案的路徑。

範例 7：建立檔案或資料夾的符號連結

此範例會建立目前資料夾中Notice.txt檔案的符號連結。

$link = New-Item -ItemType SymbolicLink -Path .\link -Target .\Notice.txt
$link | Select-Object LinkType, Target

LinkType     Target
--------     ------
SymbolicLink {.\Notice.txt}

在此範例中，Target 是 Value 參數的別名。 符號鏈接的目標必須是完整路徑。

範例 8：使用 -Force 參數嘗試重新建立資料夾

此範例會建立內含檔案的資料夾。 然後，嘗試使用 -Force建立相同的資料夾。 它不會覆寫資料夾，但只會傳回現有資料夾物件，並完整建立的檔案。

PS> New-Item -Path .\TestFolder -ItemType Directory
PS> New-Item -Path .\TestFolder\TestFile.txt -ItemType File

PS> New-Item -Path .\TestFolder -ItemType Directory -Force

    Directory: C:\
Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----         5/1/2020   8:03 AM                TestFolder

PS> Get-ChildItem .\TestFolder\

    Directory: C:\TestFolder
Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----         5/1/2020   8:03 AM              0 TestFile.txt

範例 9：使用 -Force 參數覆寫現有的檔案

此範例會建立具有 值的檔案，然後使用 重新建立檔案 -Force。 這會覆寫現有的檔案，如長度屬性所見。

PS> New-Item ./TestFile.txt -ItemType File -Value 'This is just a test file'

    Directory: C:\Source\Test
Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----         5/1/2020   8:32 AM             24 TestFile.txt

New-Item ./TestFile.txt -ItemType File -Force

    Directory: C:\Source\Test
Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----         5/1/2020   8:32 AM              0 TestFile.txt

注意

搭配 -Force 參數使用 New-Item 來建立登錄機碼時，命令的行為會與覆寫檔案時的行為相同。 如果登錄機碼已經存在，則會使用空白登錄機碼覆寫機碼和所有屬性和值。

參數

-ApplicationName

這是 WSMan 提供者提供的動態參數。 WSMan 提供者和此參數僅適用於 Windows。

指定連接中的應用程式名稱。 ApplicationName 參數的預設值為 WSMAN。

如需詳細資訊，請參閱 New-WSManInstance。

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

-Authentication

這是 WSMan 提供者提供的動態參數。 WSMan 提供者和此參數僅適用於 Windows。

指定用於伺服器的驗證機制。

如需詳細資訊，請參閱 New-WSManInstance。

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

-CertificateThumbprint

這是 WSMan 提供者提供的動態參數。 WSMan 提供者和此參數僅適用於 Windows。

指定具有執行此 WSMan 動作許可權之用戶帳戶的數位公鑰憑證 （X509）。 輸入憑證的憑證指紋。

如需詳細資訊，請參閱 New-WSManInstance。

Type:	String
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

-ConnectionURI

這是 WSMan 提供者提供的動態參數。 WSMan 提供者和此參數僅適用於 Windows。

指定 WSMan 的連接端點。

如需詳細資訊，請參閱 New-WSManInstance。

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

-Credential

注意

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

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

-Force

強制此 Cmdlet 建立可寫入現有唯讀項目的專案。 實作會因提供者而異。 即使使用 Force 參數，Cmdlet 也無法覆寫安全性限制。

您無法使用 Force 覆寫現有的連接線。 嘗試覆寫現有的連接點失敗，並出現「無法移除，因為它不是空的」錯誤。 您必須先移除現有的連接點，才能建立新的連接點。

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

-ItemType

指定新專案的提供者指定型別。 此參數的可用值取決於您所使用的目前提供者。

如果您的位置位於磁碟驅動器中 FileSystem ，則允許下列值：

• 檔案
• Directory
• SymbolicLink
• Junction
• HardLink

當您使用此方法建立檔案時，產生的檔案會編碼為UTF-8，而沒有位元組順序標記 （BOM）。

Certificate在磁碟驅動器中，以下是您可以指定的值：

• 憑證提供者
• 憑證
• 儲存
• StoreLocation

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

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

-Name

指定新項目的名稱。 您可以在 Name 或 Path 參數值中指定新項目的名稱，也可以在 Name 或 Path 值中指定新項目的路徑。 使用 Name 參數傳遞的項目名稱會相對於 Path 參數的值來建立。

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

-Options

這是別名提供者提供的動態參數。 如需詳細資訊，請參閱 New-Alias。

指定別名的 Options 屬性值。

有效值為：

• None：別名沒有條件約束（預設值）
• ReadOnly：可以使用 Force 參數刪除別名，但無法變更
• Constant：無法刪除或變更別名
• Private：別名只能在目前的範圍內使用
• AllScope：別名會複製到任何已建立的新範圍
• Unspecified：未指定選項

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

-OptionSet

這是 WSMan 提供者提供的動態參數。 WSMan 提供者和此參數僅適用於 Windows。

將一組參數傳遞至服務，以修改或精簡要求的性質。

如需詳細資訊，請參閱 New-WSManInstance。

Type:	Hashtable
Aliases:	OS
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Path

指定新專案位置的路徑。 當省略Path時，預設值為目前的位置。 您可以在 Name 中指定新項目的名稱，或將其包含在 Path 中。 使用 Name 參數傳遞的項目名稱會相對於 Path 參數的值來建立。

對於此 Cmdlet，Path 參數的運作方式就像其他 Cmdlet 的 LiteralPath 參數一樣。 不會解譯通配符。 所有字元都會傳遞至位置的提供者。 提供者可能不支援所有字元。 例如，您無法建立包含星號 （*） 字元的檔名。

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

-Port

這是 WSMan 提供者提供的動態參數。 WSMan 提供者和此參數僅適用於 Windows。

指定客戶端連線到 WinRM 服務時要使用的埠。

如需詳細資訊，請參閱 New-WSManInstance。

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

-SessionOption

這是 WSMan 提供者提供的動態參數。 WSMan 提供者和此參數僅適用於 Windows。

定義 WS-Management 工作階段的一組擴充選項。

如需詳細資訊，請參閱 New-WSManInstance。

Type:	SessionOption
Aliases:	SO
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UseSSL

這是 WSMan 提供者提供的動態參數。 WSMan 提供者和此參數僅適用於 Windows。

指定安全套接字層 （SSL） 通訊協議應該用來建立與遠端電腦的連線。 根據預設，不會使用 SSL。

如需詳細資訊，請參閱 New-WSManInstance。

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

-UseTransaction

在作用中交易中包含 命令。 只有在交易進行中時，此參數才有效。 如需詳細資訊，請參閱 about_Transactions。

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

-Value

指定新專案的值。 您也可以使用管線將值傳送至 New-Item。

Type:	Object
Aliases:	Target
Position:	Named
Default value:	None
Required:	False
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

您可以使用管線將新專案的值傳送至這個 Cmdlet。

輸出

DictionaryEntry

Cmdlet 會在建立新的環境變數時傳 回 DictionaryEntry 物件。

DirectoryInfo

Cmdlet 會在文件系統中建立新目錄時傳回 DirectoryInfo 物件。

FileInfo

Cmdlet 會在文件系統中建立新檔案時傳回 FileInfo 物件。

AliasInfo

Cmdlet 會在建立新的別名時傳 回 AliasInfo 物件。

FunctionInfo

Cmdlet 會在建立新函式時傳 回 FunctionInfo 物件。

PSVariable

Cmdlet 會在建立新的變數時傳 回 PSVariable 物件。

備註

Windows PowerShell 包含下列的 New-Item別名：

• ni

New-Item 是設計來使用任何提供者所公開的數據。 若要列出工作階段中可用的提供者，請輸入 Get-PsProvider。 如需詳細資訊，請參閱 about_Providers。

相關連結

• Clear-Item
• Copy-Item
• Get-Item
• Invoke-Item
• Move-Item
• Remove-Item
• Rename-Item
• Set-Item
• about_Providers