New-Item

  • Referência
Módulo:
Microsoft.PowerShell.Management

Cria um novo item.

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

Description

O New-Item cmdlet cria um novo item e define seu valor. Os tipos de itens que podem ser criados dependem do local do item. Por exemplo, no sistema de arquivos, New-Item cria arquivos e pastas. No Registro, New-Item cria chaves e entradas do Registro.

New-Item também pode definir o valor dos itens que ele cria. Por exemplo, quando ele cria um novo arquivo, New-Item pode adicionar conteúdo inicial ao arquivo.

Exemplos

Exemplo 1: Criar um arquivo no diretório atual

Esse comando cria um arquivo de texto chamado "testfile1.txt" no diretório atual. O ponto ('.') no valor do parâmetro Path indica o diretório atual. O texto entre aspas que segue o parâmetro Valor é adicionado ao arquivo como conteúdo.

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

Exemplo 2: Criar um diretório

Esse comando cria um diretório chamado "Logfiles" na C: unidade. O parâmetro ItemType especifica que o novo item é um diretório, não um arquivo ou outro objeto do sistema de arquivos.

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

Exemplo 3: Criar um perfil

Esse comando cria um perfil do PowerShell no caminho especificado pela $profile variável.

Você pode usar perfis para personalizar o PowerShell. $profile é uma variável automática (interna) que armazena o caminho e o nome do arquivo do perfil "CurrentUser/CurrentHost". Por padrão, o perfil não existe, embora o PowerShell armazene um caminho e um nome de arquivo para ele.

Nesse comando, a $profile variável representa o caminho do arquivo. O parâmetro ItemType especifica que o comando cria um arquivo. O parâmetro Force permite criar um arquivo no caminho do perfil, mesmo quando os diretórios no caminho não existem.

Depois de criar um perfil, você pode inserir aliases, funções e scripts no perfil para personalizar o shell.

Para obter mais informações, consulte about_Automatic_Variables e about_Profiles.

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

Exemplo 4: Criar um diretório em um diretório diferente

Este exemplo cria um novo diretório Scripts no diretório "C:\PS-Test".

O nome do novo item de diretório, "Scripts", está incluído no valor do parâmetro Path , em vez de ser especificado no valor de Nome. Conforme indicado pela sintaxe, ambos os formatos de comando são válidos.

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

Exemplo 5: Criar vários arquivos

Este exemplo cria arquivos em dois diretórios diferentes. Como o Path usa várias cadeias de caracteres, você pode usá-la para criar vários itens.

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

Exemplo 6: Usar caracteres curinga para criar arquivos em vários diretórios

O New-Item cmdlet dá suporte a caracteres curinga no parâmetro Path . O comando a seguir cria um temp.txt arquivo em todos os diretórios especificados pelos caracteres curinga no parâmetro 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

O Get-ChildItem cmdlet mostra três diretórios no C:\Temp diretório. Usando caracteres curinga, o New-Item cmdlet cria um temp.txt arquivo em todos os diretórios no diretório atual. O New-Item cmdlet gera os itens que você criou, que são canalizados para Select-Object verificar os caminhos dos arquivos recém-criados.

Este exemplo cria um link simbólico para o arquivo Notice.txt na pasta atual.

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

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

Neste exemplo, Target é um alias para o parâmetro Value . O destino do link simbólico pode ser um caminho relativo. Antes do PowerShell v6.2, o destino deve ser um caminho totalmente qualificado.

A partir do PowerShell 7.1, agora você pode criar um SymbolicLink para uma pasta no Windows usando um caminho relativo.

Exemplo 8: Usar o parâmetro -Force para tentar recriar pastas

Este exemplo cria uma pasta com um arquivo dentro. Em seguida, tenta criar a mesma pasta usando -Force. Ele não substituirá a pasta, mas simplesmente retornará o objeto de pasta existente com o arquivo criado intacto.

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

Exemplo 9: Usar o parâmetro -Force para substituir arquivos existentes

Este exemplo cria um arquivo com um valor e recria o arquivo usando -Force. Isso substitui o arquivo existente e ele perderá o conteúdo, como você pode ver pela propriedade length

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

Observação

Ao usar New-Item com a opção -Force para criar chaves do Registro, o comando se comportará da mesma forma que ao substituir um arquivo. Se a chave do Registro já existir, a chave e todas as propriedades e valores serão substituídos com uma chave vazia do Registro.

Parâmetros

-Confirm

Solicita sua confirmação antes de executar o cmdlet.

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

-Credential

Observação

Não há suporte para esse parâmetro em nenhum provedor instalado com o PowerShell. Para representar outro usuário ou elevar suas credenciais ao executar este cmdlet, use Invoke-Command.

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

-Force

Força esse cmdlet a criar um item que grava em um item somente leitura existente. A implementação varia de provedor para provedor. Mesmo usando o parâmetro Force , o cmdlet não pode substituir as restrições de segurança.

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

-ItemType

Especifica o tipo de provedor especificado do novo item. Os valores disponíveis desse parâmetro dependem do provedor atual que você está usando.

Se o local estiver em uma FileSystem unidade, os seguintes valores serão permitidos:

  • Arquivo
  • Diretório
  • SymbolicLink
  • Junção
  • HardLink

Observação

Criar um SymbolicLink tipo no Windows requer elevação como administrador. No entanto, Windows 10 (build 14972 ou mais recente) com o Modo de Desenvolvedor habilitado não requer mais elevação criando links simbólicos.

Em uma Certificate unidade, estes são os valores que você pode especificar:

  • Provedor Certificate
  • Certificado
  • Repositório
  • StoreLocation

Para obter mais informações , consulte about_Providers.

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

-Name

Especifica o nome do novo item. Você pode especificar o nome do novo item no valor do parâmetro Nome ou Caminho e especificar o caminho do novo item no valor Nome ou Caminho . Os nomes de itens passados usando o parâmetro Name são criados em relação ao valor do parâmetro Path .

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

-Path

Especifica o caminho do local do novo item. O padrão é o local atual quando o Caminho é omitido. Você pode especificar o nome do novo item em Nome ou incluí-lo no Caminho. Os nomes de itens passados usando o parâmetro Name são criados em relação ao valor do parâmetro Path .

Para esse cmdlet, o parâmetro Path funciona como o parâmetro LiteralPath de outros cmdlets. Caracteres curinga não são interpretados. Todos os caracteres são passados para o provedor do local. O provedor pode não dar suporte a todos os caracteres. Por exemplo, você não pode criar um nome de arquivo que contenha um caractere asterisco (*).

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

-Value

Especifica o valor do novo item. Você também pode canalizar um valor para New-Item.

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

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

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

Entradas

Object

Você pode canalizar um valor para o novo item para este cmdlet.

Saídas

Object

Esse cmdlet retorna o item que ele cria.

Observações

New-Item foi projetado para trabalhar com os dados expostos por qualquer provedor. Para listar os provedores disponíveis em sua sessão, digite Get-PsProvider. Para obter mais informações, consulte about_Providers.