New-Item

模块:

Microsoft.PowerShell.Management

创建新项。

语法

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

说明

New-Item cmdlet 创建新项并设置该项的值。 可创建项的类型取决于该项所在位置。 例如，在文件系统中，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：创建目录

此命令将在 C: 驱动器中创建名为“Logfiles”的目录。 ItemType 参数指定新项是目录，而不是文件或其他文件系统对象。

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

示例 3：创建配置文件

此命令在由 $profile 变量指定的路径中创建一个 PowerShell 配置文件。

你可以使用配置文件来自定义 PowerShell。 $profile 是用于存储“CurrentUser/CurrentHost”配置文件的路径和文件名的一个自动（内置）变量。 默认情况下此配置文件不存在，即使如此，PowerShell 也为其存储了路径和文件名。

在此命令中，$profile 变量代表文件的路径。 ItemType 参数指定该命令创建一个文件。 Force 参数允许在配置文件路径中创建文件，即使路径中的目录不存在也是如此。

创建配置文件之后，你可以在此配置文件中输入别名、函数和脚本来自定义你的 shell。

有关详细信息，请参阅 about_Automatic_Variables 和 about_Profiles。

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

示例 4：在不同的目录中创建目录

此示例将在“C:\PS-Test”目录中创建新的脚本目录。

新目录项的名称“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：使用通配符在多个目录中创建文件

New-Item cmdlet 支持在 Path 参数中使用通配符。 以下命令会在 Path 参数中的通配符指定的所有目录中创建一个 temp.txt 文件。

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

Get-ChildItem cmdlet 显示 C:\Temp 目录下的三个目录。 New-Item cmdlet 使用通配符在当前目录下的所有目录中创建一个 temp.txt 文件。 New-Item cmdlet 会输出创建的项目，该项目通过管道传输到 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 参数的别名。 符号链接的目标可以是相对路径。 在 PowerShell v6.2 之前，目标必须是完全限定的路径。

从 PowerShell 7.1 开始，现在可以使用相对路径创建到 Windows 上的文件夹的 SymbolicLink。

示例 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
• 交接点
• HardLink

注意

在 Windows 上创建 SymbolicLink 类型需要以管理员身份提升。 但是，启用了开发人员模式的 Windows 10（内部版本 14972 或更高版本）不再需要提升创建符号链接。

在 Certificate 驱动器中，可以指定以下值：

• 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

这是 Alias 提供程序提供的动态参数。 有关详细信息，请参阅 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