New-Item

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

Cria um novo item.

Sintaxe

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

O New-Item cmdlet cria um novo item e define seu valor. Os tipos de itens que podem ser criados dependem da localização 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 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

Este 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 citado que segue o parâmetro Value é 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

Este 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

Este 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, mesmo que o PowerShell armazene um caminho e um nome de arquivo para ele.

Neste 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 seu shell.

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

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

Nota

Quando você cria um arquivo usando esse método, o arquivo resultante é codificado como UTF-8 sem uma marca de ordem de bytes (BOM).

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", é incluído no valor do parâmetro Path , em vez de ser especificado no valor de Name. Conforme indicado pela sintaxe, qualquer forma de comando é válida.

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á-lo para criar vários itens.

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

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

O New-Item cmdlet oferece suporte a curingas no parâmetro Path . O comando a seguir cria um temp.txt arquivo em todos os diretórios especificados pelos curingas 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 sob o C:\Temp diretório. Usando curingas, o New-Item cmdlet cria um temp.txt arquivo em todos os diretórios do diretório atual. O New-Item cmdlet gera a saída dos 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 alvo da ligação simbólica deve ser um caminho plenamente qualificado.

Exemplo 8: Use 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 -Forceo . 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: Use o parâmetro -Force para substituir arquivos existentes

Este exemplo cria um arquivo com um valor e, em seguida, recria o arquivo usando -Force. Isso substitui o arquivo existente, 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

Nota

Ao usar New-Item com o -Force switch 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 por uma chave do Registro vazia.

Parâmetros

-ApplicationName

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan . O provedor WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica o nome do aplicativo na conexão. O valor padrão do parâmetro ApplicationName é WSMAN.

Para obter mais informações, consulte New-WSManInstance.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Authentication

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan . O provedor WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica o mecanismo de autenticação a ser usado no servidor.

Para obter mais informações, consulte New-WSManInstance.

Tipo:AuthenticationMechanism
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-CertificateThumbprint

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan . O provedor WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica o certificado de chave pública digital (X509) de uma conta de usuário que tem permissão para executar essa ação WSMan. Insira a impressão digital do certificado.

Para obter mais informações, consulte New-WSManInstance.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Confirm

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

Tipo:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ConnectionURI

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan . O provedor WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica o ponto de extremidade de conexão para o WSMan.

Para obter mais informações, consulte New-WSManInstance.

Tipo:Uri
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Credential

Nota

Esse parâmetro não é suportado por nenhum provedor instalado com o PowerShell. Para representar outro usuário ou elevar suas credenciais ao executar este cmdlet, use Invoke-Command.

Tipo:PSCredential
Position:Named
Default value:Current user
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Force

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

Não é possível usar Force para substituir uma junção existente. As tentativas de substituir uma junção existente falham com um erro "não pode ser removido porque não está vazio". Você deve remover a junção existente antes de criar uma nova.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ItemType

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

Se a sua localização estiver numa FileSystem unidade, são permitidos os seguintes valores:

  • File
  • Directory
  • SymbolicLink
  • Junction
  • HardLink

Quando você cria um arquivo usando esse método, o arquivo resultante é codificado como UTF-8 sem uma marca de ordem de bytes (BOM).

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

  • Certificate Provider
  • Certificate
  • Store
  • StoreLocation

Para obter mais informações, consulte about_Providers.

Tipo:String
Aliases:Type
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Name

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

Tipo:String
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Options

Este é um parâmetro dinâmico disponibilizado pelo provedor Alias . Para obter mais informações, consulte New-Alias.

Especifica o valor da propriedade Options de um alias.

Os valores válidos são:

  • None: O alias não tem restrições (valor padrão)
  • ReadOnly: O alias pode ser excluído, mas não pode ser alterado sem usar o parâmetro Force
  • Constant: O alias não pode ser excluído ou alterado
  • Private: O alias está disponível apenas no escopo atual
  • AllScope: O alias é copiado para todos os novos escopos criados
  • Unspecified: A opção não está especificada
Tipo:ScopedItemOptions
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-OptionSet

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan . O provedor WSMan e esse parâmetro só estão disponíveis no Windows.

Passa um conjunto de opções para um serviço para modificar ou refinar a natureza da solicitação.

Para obter mais informações, consulte New-WSManInstance.

Tipo:Hashtable
Aliases:OS
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Path

Especifica o caminho do local do novo item. O padrão é o local atual quando Path é 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 este cmdlet, o parâmetro Path funciona como o parâmetro LiteralPath de outros cmdlets. Os caracteres curinga não são interpretados. Todos os caracteres são passados para o provedor do local. O provedor pode não suportar todos os caracteres. Por exemplo, não é possível criar um nome de arquivo que contenha um caractere de asterisco (*).

Tipo:String[]
Position:0
Default value:Current location
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Port

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan . O provedor WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica a porta a ser usada quando o cliente se conecta ao serviço WinRM.

Para obter mais informações, consulte New-WSManInstance.

Tipo:Int32
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-SessionOption

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan . O provedor WSMan e esse parâmetro só estão disponíveis no Windows.

Define um conjunto de opções estendidas para a sessão WS-Management.

Para obter mais informações, consulte New-WSManInstance.

Tipo:SessionOption
Aliases:SO
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-UseSSL

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan . O provedor WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica que o protocolo SSL (Secure Sockets Layer) deve ser usado para estabelecer uma conexão com o computador remoto. Por padrão, o SSL não é usado.

Para obter mais informações, consulte New-WSManInstance.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-UseTransaction

Inclui o comando na transação ativa. Este parâmetro é válido somente quando uma transação está em andamento. Para obter mais informações, consulte about_Transactions.

Tipo:SwitchParameter
Aliases:usetx
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Value

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

Tipo:Object
Aliases:Target
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-WhatIf

Apresenta o que aconteceria mediante a execução do cmdlet. O cmdlet não é executado.

Tipo:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

Object

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

Saídas

DictionaryEntry

O cmdlet retorna um objeto DictionaryEntry ao criar uma nova variável de ambiente.

DirectoryInfo

O cmdlet retorna um objeto DirectoryInfo ao criar um novo diretório no sistema de arquivos.

FileInfo

O cmdlet retorna um objeto FileInfo ao criar um novo arquivo no sistema de arquivos.

AliasInfo

O cmdlet retorna um objeto AliasInfo ao criar um novo alias.

FunctionInfo

O cmdlet retorna um objeto FunctionInfo ao criar uma nova função.

PSVariable

O cmdlet retorna um objeto PSVariable ao criar uma nova variável.

Notas

O Windows PowerShell inclui os seguintes aliases para New-Item:

  • ni

New-Item é 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.