New-Item

模組:

Microsoft.PowerShell.Management

建立新的項目。

Syntax

New-Item
   [-Path] <String[]>
   [-ItemType <String>]
   [-Value <Object>]
   [-Force]
   [-Credential <PSCredential>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-Item
   [[-Path] <String[]>]
   -Name <String>
   [-ItemType <String>]
   [-Value <Object>]
   [-Force]
   [-Credential <PSCredential>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-Item
   [-Path] <string[]>
   -ConnectionURI <uri>
   [-ItemType <string>]
   [-Value <Object>]
   [-Force]
   [-Credential <pscredential>]
   [-WhatIf]
   [-Confirm]
   [-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]
   [-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]
   [-Options <ScopedItemOptions>]
   [<CommonParameters>]

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

Description

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

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

範例

範例 1：Create 目前目錄中的檔案

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

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

範例 2：Create 目錄

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

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

範例 3：Create 配置檔

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

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

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

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

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

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

範例 4：Create 不同目錄中的目錄

本範例會在 “C：\PS-Test” 目錄中建立新的 Scripts 目錄。

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

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

範例 5：Create 多個檔案

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

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

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

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

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：Create 檔案或資料夾的符號連結

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

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

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

在此範例中， Target 是 Value 參數的別名。 符號鏈接的目標可以是相對路徑。 在 PowerShell v6.2 之前，目標必須是完整路徑。

從 PowerShell 7.1 開始，您現在可以使用相對路徑，建立至 Windows 上資料夾的 符號連結 。

範例 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 ，則允許下列值：

• 檔案
• 目錄
• SymbolicLink
• 接合
• HardLink

注意

在 Windows 上建立 SymbolicLink 類型需要以系統管理員身分提高許可權。 不過，Windows 10 (啟用開發人員模式的組建 14972 或更新版本) 不再需要提高許可權建立符號連結。

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:	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 物件。

備註

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